@needle-tools/engine 5.1.0-canary.db0c38f → 5.1.0-canary.e6680fa

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
 
@@ -106,11 +106,43 @@ enum LightShadows {
 export class Light extends Behaviour implements ILight {
 
     /**
-     * The type of light (spot, directional, point, etc.)  
-     * Can not be changed at runtime.  
+     * The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"`.
+     * Implements {@link ILight.type}. Can not be changed at runtime.
      */
+    get type(): ILight["type"] {
+        return this._type;
+    }
+
+    /** Numeric LightType serialized from Unity/Blender — converts to string on write */
     @serializable()
-    private type: LightType = 0;
+    set type(value: LightType | ILight["type"]) {
+        if (this.light && this.__didAwake) {
+            throw new Error("Changing the light type at runtime is not supported");
+        }
+        switch (value) {
+            case LightType.Directional:
+                this._type = "directional";
+                break;
+            case LightType.Point:
+                this._type = "point";
+                break;
+            case LightType.Spot:
+                this._type = "spot";
+                break;
+            case "directional":
+            case "point":
+            case "spot":
+                this._type = value;
+                break;
+            default:
+                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";
+
 
     /**
      * The maximum distance the light affects.  
@@ -345,7 +377,7 @@ export class Light extends Behaviour implements ILight {
      */
     public getWorldPosition(vec: Vector3): Vector3 {
         if (this.light) {
-            if (this.type === LightType.Directional) {
+            if (this.type === "directional") {
                 return this.light.getWorldPosition(vec).multiplyScalar(1);
             }
             return this.light.getWorldPosition(vec);
@@ -372,12 +404,13 @@ export class Light extends Behaviour implements ILight {
             else if (this.light.parent !== this.gameObject)
                 this.gameObject.add(this.light);
         }
-        if (this.type === LightType.Directional)
-            this.startCoroutine(this.updateMainLightRoutine(), FrameEvent.LateUpdate);
+        this.context.lights.push(this);
     }
 
     onDisable() {
         if (debug) console.log("DISABLE LIGHT", this.name);
+        const index = this.context.lights.indexOf(this);
+        if (index !== -1) this.context.lights.splice(index, 1);
         if (this.light) {
             if (this.selfIsLight)
                 this.light.intensity = 0;
@@ -399,14 +432,14 @@ export class Light extends Behaviour implements ILight {
             this._intensity = this.light.intensity;
 
             switch (this.type) {
-                case LightType.Directional:
+                case "directional":
                     this.setDirectionalLight(this.light as DirectionalLight);
                     break;
             }
         }
         else if (!this.light) {
             switch (this.type) {
-                case LightType.Directional:
+                case "directional":
                     // console.log(this);
                     const dirLight = new DirectionalLight(this.color, this.intensity * Math.PI);
                     // directional light target is at 0 0 0 by default
@@ -425,7 +458,7 @@ export class Light extends Behaviour implements ILight {
                     }
                     break;
 
-                case LightType.Spot:
+                case "spot":
                     const spotLight = new SpotLight(this.color, this.intensity * Math.PI, this.range, toRadians(this.spotAngle / 2), 1 - toRadians(this.innerSpotAngle / 2) / toRadians(this.spotAngle / 2), 2);
                     spotLight.position.set(0, 0, 0);
                     spotLight.rotation.set(0, 0, 0);
@@ -437,13 +470,18 @@ export class Light extends Behaviour implements ILight {
                     spotLightTarget.rotation.set(0, 0, 0);
                     break;
 
-                case LightType.Point:
+                case "point":
                     const pointLight = new PointLight(this.color, this.intensity * Math.PI, this.range);
                     this.light = pointLight;
 
                     // 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;
+
             }
         }
 
@@ -526,22 +564,6 @@ export class Light extends Behaviour implements ILight {
 
     }
 
-    /**
-     * Coroutine that updates the main light reference in the context
-     * if this directional light should be the main light
-     */
-    *updateMainLightRoutine() {
-        while (true) {
-            if (this.type === LightType.Directional) {
-                if (!this.context.mainLight || this.intensity > this.context.mainLight.intensity) {
-                    this.context.mainLight = this;
-                }
-                yield;
-            }
-            break;
-        }
-    }
-
     /**
      * Controls whether the renderer's shadow map type can be changed when soft shadows are used
      */

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

@@ -582,7 +582,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
     };
 
     private _onPointerUpLate = (evt: NEPointerEvent) => {
-        if (this.doubleClickToFocus && evt.isDoubleClick && !evt.used) {
+        if (this.doubleClickToFocus && evt.isDoubleClick && !evt.used && this.canFocusAtPointer()) {
             this.setTargetFromRaycast();
         }
         // Automatically update the camera focus
@@ -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) {
@@ -708,7 +716,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
             }
         }
 
-        const focusAtPointer = (this.middleClickToFocus && this.context.input.getPointerClicked(1));
+        const focusAtPointer = (this.middleClickToFocus && this.context.input.getPointerClicked(1) && this.canFocusAtPointer());
         if (focusAtPointer) {
             this.setTargetFromRaycast();
         }
@@ -758,19 +766,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 +862,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 +1038,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) {
@@ -1063,6 +1080,12 @@ export class OrbitControls extends Behaviour implements ICameraController {
         if (this.lookAtTarget && this.lockLookAtTarget) this.lookAtTarget.worldPosition = this._controls.target;
     }
 
+    private canFocusAtPointer(): boolean {
+        // A locked lookAtTarget is the authoritative orbit center. Pointer focus would
+        // otherwise move the assigned scene object via lerpLookTarget's back-sync.
+        return !(this.lookAtTarget && this.lockLookAtTarget);
+    }
+
     private setTargetFromRaycast(ray?: Ray, immediateOrDuration: number | boolean = false): boolean {
         if (!this.controls) return false;
         const rc = ray ? this.context.physics.raycastFromRay(ray) : this.context.physics.raycast();
@@ -1086,13 +1109,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 {
 
 

package/src/engine-components/ReflectionProbe.ts

@@ -290,6 +290,8 @@ export class ReflectionProbe extends Behaviour {
             const current = block.getOverride("envMap")?.value;
             if (current === this.texture) {
                 block.removeOveride("envMap");
+                block.removeOveride("envMapRotation");
+                block.removeOveride("envMapIntensity");
             }
         }
     }

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

@@ -747,6 +747,9 @@ export class SceneSwitcher extends Behaviour {
                 const openedEvt = new CustomEvent<LoadSceneEvent>("scene-opened", { detail: { scene: scene, switcher: this, index: index } });
                 this.dispatchEvent(openedEvt);
                 this.sceneLoaded?.invoke(this);
+                if (this._currentSceneAsset) {
+                    this.context.events.emit("scene-content-changed", { source: this, object: this._currentSceneAsset });
+                }
                 return true;
             }
         }

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

@@ -207,16 +207,13 @@ export class VideoPlayer extends Behaviour {
      */
     get isPlaying(): boolean {
         const video = this._videoElement;
-        if (video) {
-            if (video.currentTime > 0 && !video.paused && !video.ended
-                && video.readyState > video.HAVE_CURRENT_DATA)
-                return true;
-            else if (video.srcObject) {
-                const stream = video.srcObject as MediaStream;
-                if (stream.active) return true;
-            }
+        if (!video) return false;
+        if (video.paused || video.ended) return false;
+        if (video.srcObject) {
+            const stream = video.srcObject as MediaStream;
+            return stream.active;
         }
-        return false;
+        return video.currentTime > 0 && video.readyState > video.HAVE_CURRENT_DATA;
     }
 
     get crossOrigin(): string | null {
@@ -430,26 +427,52 @@ export class VideoPlayer extends Behaviour {
 
     private _playErrors: number = 0;
 
-    /** start playing the video source */
-    play() {
+    /**
+     * Plays the assigned video clip, URL, or MediaStream.
+     * If a `clip` argument is passed, it is used as the new video source (mirroring {@link AudioSource.play}).
+     *
+     * @param clip - Optional video URL string or {@link MediaStream} to play. If omitted, plays the currently assigned source.
+     * @returns A promise that resolves to `true` when playback was successfully started, or `false` on error.
+     */
+    async play(clip?: string | MediaStream): Promise<boolean> {
+        // Defensive: if called from an event handler with a non-string/non-MediaStream argument
+        // (e.g. SpatialTrigger.onEnter passes a receiver object), ignore the arg and fall back to the assigned source.
+        // Same pattern as AudioSource.play.
+        if (clip !== undefined && typeof clip !== "string" && !(clip instanceof MediaStream)) {
+            if (isDevEnvironment()) console.warn("[VideoPlayer] Called play with unknown argument type. Using assigned source instead.", clip);
+            clip = undefined;
+        }
+
+        if (typeof clip === "string") {
+            this.setClipURL(clip);
+        }
+        else if (clip instanceof MediaStream) {
+            this.setVideo(clip);
+        }
+
         if (!this._videoElement) this.create(false);
         if (!this._videoElement) {
             if (debug) console.warn("Can not play: no video element found", this);
-            return
+            return false;
         }
-        if (this._isPlaying && !this._videoElement?.ended && !this._videoElement?.paused) return;
+        if (this._isPlaying && !this._videoElement?.ended && !this._videoElement?.paused) return true;
         this._isPlaying = true;
         if (!this._receivedInput) this._videoElement.muted = true;
         this.handleBeginPlaying(false);
 
         if (this.shouldUseM3U) {
             this.ensureM3UCanBePlayed();
-            return;
+            return true;
         }
 
         if (debug) console.log("Video Play()", this.clip, this._videoElement, this.time);
         this._videoElement.currentTime = this.time;
-        this._videoElement.play().catch(err => {
+        try {
+            await this._videoElement.play();
+            if (debug) console.log("play", this._videoElement, this.time);
+            return true;
+        }
+        catch (err: any) {
             if (this._playErrors++ < 10) console.error(err);
             else if (this._playErrors === 10) console.error("Multiple errors playing video, further errors will be suppressed. Use 'debugvideo' param to see all errors.");
             // https://developer.chrome.com/blog/play-request-was-interrupted/
@@ -459,8 +482,8 @@ export class VideoPlayer extends Behaviour {
                 if (this._isPlaying && !this.destroyed && this.activeAndEnabled)
                     this.play();
             }, 1000);
-        });
-        if (debug) console.log("play", this._videoElement, this.time);
+            return false;
+        }
     }
 
     /**