@needle-tools/engine 5.1.0-canary.deec6e4 → 5.1.0-canary.e7c2511

package/src/engine-components/DragControls.ts

@@ -10,8 +10,8 @@ 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";
 import { Rigidbody } from "./RigidBody.js";
 import { SyncedTransform } from "./SyncedTransform.js";
@@ -155,7 +155,19 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
     @serializable()
     public showGizmo: boolean = false;
 
-    /** 
+    /** Invoked once when a drag begins (after the minimum drag distance threshold is met). */
+    @serializable(EventList)
+    dragStarted: EventList = new EventList();
+
+    /** Invoked every frame while the object is being dragged. */
+    @serializable(EventList)
+    dragUpdated: EventList = new EventList();
+
+    /** Invoked once when the last pointer is released and the drag ends. */
+    @serializable(EventList)
+    dragEnded: EventList = new EventList();
+
+    /**
      * Returns the object currently being dragged by this DragControls component, if any.
      * @returns The object being dragged or null if no object is currently dragged
      */
@@ -457,6 +469,7 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         if (!object) return;
 
         this._isDragging = true;
+        this.dragStarted?.invoke();
 
         const sync = GameObject.getComponentInChildren(object, SyncedTransform);
         if (debug) console.log("DRAG START", sync, object);
@@ -497,9 +510,10 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         const object = this._targetObject || this.gameObject;
 
         InstancingUtil.markDirty(object);
+        this.dragUpdated?.invoke();
     }
 
-    /** 
+    /**
      * Called when the last pointer has been removed from this object.
      * Cleans up drag state and applies final velocities to rigidbodies.
      * @param evt Pointer event data for the last pointer that was lifted
@@ -507,6 +521,7 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
     private onLastDragEnd(evt: PointerEventData | null) {
         if (!this || !this._isDragging) return;
         this._isDragging = false;
+        this.dragEnded?.invoke();
         for (const rb of this._draggingRigidbodies) {
             rb.setVelocity(rb.smoothedVelocity.multiplyScalar(this.context.time.deltaTime));
         }
@@ -1484,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;
@@ -1508,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/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/Networking.ts

@@ -37,7 +37,7 @@ const debug = getParam("debugnet");
  * @see {@link RoomEvents} for room lifecycle events
  * @see {@link isLocalNetwork} for local network detection
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
- * @summary Networking configuration
+ * @summary Configures the websocket server URL for multiplayer networking
  * @category Networking
  * @group Components
  */

package/src/engine-components/OrbitControls.ts

@@ -758,19 +758,26 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
         if (this.targetBounds) {
             // #region target bounds
-            const targetVector = this._controls.target;
             const boundsCenter = this.targetBounds.worldPosition;
             const boundsHalfSize = getTempVector(this.targetBounds.worldScale).multiplyScalar(0.5);
             const min = getTempVector(boundsCenter).sub(boundsHalfSize);
             const max = getTempVector(boundsCenter).add(boundsHalfSize);
-            const newTarget = getTempVector(this._controls.target).clamp(min, max);
-            const duration = .1;
-            if (duration <= 0) targetVector.copy(newTarget);
-            else targetVector.lerp(newTarget, this.context.time.deltaTime / duration);
+
             if (this._lookTargetLerpActive) {
-                if (duration <= 0) this._lookTargetEndPosition.copy(newTarget);
-                else this._lookTargetEndPosition.lerp(newTarget, this.context.time.deltaTime / (duration * 5));
+                // During a programmatic transition (fitCamera / setLookTargetPosition with immediate: false),
+                // only clamp the destination. The look-target lerp (above) handles moving _controls.target
+                // towards the endpoint — we must not fight it by also lerping _controls.target here.
+                this._lookTargetEndPosition.clamp(min, max);
+            }
+            else {
+                // Interactive use (pan/orbit): smoothly push the target back into bounds
+                const targetVector = this._controls.target;
+                const newTarget = getTempVector(targetVector).clamp(min, max);
+                const duration = .1;
+                if (duration <= 0) targetVector.copy(newTarget);
+                else targetVector.lerp(newTarget, Math.min(1, this.context.time.deltaTime / duration));
             }
+
             if (debug) {
                 Gizmos.DrawWireBox(boundsCenter, boundsHalfSize.multiplyScalar(2), 0xffaa00);
             }
@@ -847,7 +854,8 @@ export class OrbitControls extends Behaviour implements ICameraController {
                 this._controls.update(this.context.time.deltaTime);
 
                 if (debug) {
-                    Gizmos.DrawWireSphere(this._controls.target, 0.1, 0x00ff00);
+                    const distance = this._controls.getDistance();
+                    Gizmos.DrawWireSphere(this._controls.target, 0.01 * distance, 0x00ff00);
                 }
             }
         }
@@ -1022,7 +1030,8 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
         if (debug) {
             console.warn("OrbitControls: setLookTargetPosition", position, immediateOrDuration);
-            Gizmos.DrawWireSphere(this._lookTargetEndPosition, .2, 0xff0000, 2);
+            const distance = this._controls.getDistance();
+            Gizmos.DrawWireSphere(this._lookTargetEndPosition, 0.01 * distance, 0xff5500, 2);
         }
 
         if (immediateOrDuration === true) {

package/src/engine-components/RigidBody.ts

@@ -204,12 +204,19 @@ export class Rigidbody extends Behaviour implements IRigidbody {
 
     get isRigidbody() { return true; }
 
-    /** When true the mass will be automatically calculated by the attached colliders */
+    /** When true the mass is automatically computed from the attached colliders using `mass = density × volume`.
+     * Each collider's {@link Collider.density} determines how heavy it contributes to the total mass.
+     * Disable to set mass explicitly via the `mass` property.
+     */
     @validate()
     autoMass: boolean = true;
 
-    /** By default the mass will be automatically calculated (see `autoMass`) by the physics engine using the collider sizes  
-     * To set the mass manually you can either set the `mass` value or set `autoMass` to `false`
+    /** The mass of the rigidbody in kg (when `autoMass` is disabled).
+     * When `autoMass` is enabled, reading this returns the computed mass from `density × volume` of all attached colliders.
+     * Setting this property automatically disables `autoMass`.
+     *
+     * **Prefer using {@link Collider.density}** with `autoMass` enabled instead — density scales
+     * naturally with collider size, while explicit mass stays fixed regardless of shape changes.
      */
     @serializable()
     set mass(value: number) {
@@ -403,9 +410,16 @@ export class Rigidbody extends Behaviour implements IRigidbody {
         this.context.physics.engine?.removeBody(this);
     }
 
-    onValidate() {
+    onValidate(property?: string) {
         this._propertiesChanged = true;
+        if (property === "autoMass" && !this.autoMass) {
+            if (isDevEnvironment() && !Rigidbody._didWarnAutoMass) {
+                Rigidbody._didWarnAutoMass = true;
+                console.warn("[Rigidbody] autoMass disabled — consider using Collider.density instead of setting mass explicitly. Density scales naturally with collider size.");
+            }
+        }
     }
+    private static _didWarnAutoMass = false;
 
     // need to do this right before updating physics to prevent rendered object glitching through physical bodies
     * beforePhysics() {

package/src/engine-components/SeeThrough.ts

@@ -249,10 +249,10 @@ export class SeeThrough extends Behaviour {
             }
 
             const materials = renderer.sharedMaterials;// : this.rendererMaterials.get(renderer);
-            if (!materials) return;
+            if (!materials?.length) return;
 
             const block = MaterialPropertyBlock.get(renderer.gameObject);
-            const currentOpacity = (block.getOverride("opacity")?.value ?? materials[0].opacity ?? 1);
+            const currentOpacity = (block.getOverride("opacity")?.value ?? materials[0]?.opacity ?? 1);
 
             let newAlpha = Mathf.lerp(currentOpacity, targetAlpha, duration <= 0 ? 1 : this.context.time.deltaTime / duration);;
             if (newAlpha >= 0.99) newAlpha = 1;

package/src/engine-components/api.ts

@@ -34,8 +34,8 @@
  * @module Built-in Components
  */
 
+export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.builder.js";
 export * from "./codegen/components.js";
-export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.js";
 export { Collider } from "./Collider.js"; // export abstract type
 export { Behaviour, Component, GameObject } from "./Component.js";
 

package/src/engine-components/codegen/components.ts

@@ -6,18 +6,10 @@ export { Animation } from "../Animation.js";
 export { Keyframe } from "../AnimationCurve.js";
 export { AnimationCurve } from "../AnimationCurve.js";
 export { Animator } from "../Animator.js";
-export { AnimatorControllerBuilder } from "../AnimatorController.js";
+export { AnimatorControllerBuilder } from "../AnimatorController.builder.js";
 export { AnimatorController } from "../AnimatorController.js";
 export { AudioListener } from "../AudioListener.js";
 export { AudioSource } from "../AudioSource.js";
-export { Avatar_POI } from "../avatar/Avatar_Brain_LookAt.js";
-export { Avatar_Brain_LookAt } from "../avatar/Avatar_Brain_LookAt.js";
-export { Avatar_MouthShapes } from "../avatar/Avatar_MouthShapes.js";
-export { Avatar_MustacheShake } from "../avatar/Avatar_MustacheShake.js";
-export { AvatarBlink_Simple } from "../avatar/AvatarBlink_Simple.js";
-export { AvatarEyeLook_Rotation } from "../avatar/AvatarEyeLook_Rotation.js";
-export { AvatarModel } from "../AvatarLoader.js";
-export { AvatarLoader } from "../AvatarLoader.js";
 export { AxesHelper } from "../AxesHelper.js";
 export { BasicIKConstraint } from "../BasicIKConstraint.js";
 export { BoxHelperComponent } from "../BoxHelperComponent.js";
@@ -172,7 +164,9 @@ export { AnimationTrackHandler } from "../timeline/TimelineTracks.js";
 export { AudioTrackHandler } from "../timeline/TimelineTracks.js";
 export { MarkerTrackHandler } from "../timeline/TimelineTracks.js";
 export { SignalTrackHandler } from "../timeline/TimelineTracks.js";
+export { ActivationTrackHandler } from "../timeline/TimelineTracks.js";
 export { ControlTrackHandler } from "../timeline/TimelineTracks.js";
+export { TimelineBuilder } from "../timeline/TimelineBuilder.js";
 export { TransformGizmo } from "../TransformGizmo.js";
 export { BaseUIComponent } from "../ui/BaseUIComponent.js";
 export { UIRootComponent } from "../ui/BaseUIComponent.js";