@needle-tools/engine 5.1.0-canary.30cc545 → 5.1.0-canary.40da791

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

@@ -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) {
@@ -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) {
@@ -1086,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 {
 
 

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

@@ -34,8 +34,9 @@
  * @module Built-in Components
  */
 
+export { AnimationBuilder, type AnimationKeyframe, type Tween, type AnimationInterpolation } from "./AnimationBuilder.js";
+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

@@ -3,21 +3,13 @@
 export class __Ignore {}
 export { AlignmentConstraint } from "../AlignmentConstraint.js";
 export { Animation } from "../Animation.js";
+export { AnimationBuilder } from "../AnimationBuilder.js";
 export { Keyframe } from "../AnimationCurve.js";
 export { AnimationCurve } from "../AnimationCurve.js";
 export { Animator } from "../Animator.js";
-export { AnimatorControllerBuilder } from "../AnimatorController.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";
@@ -168,11 +160,13 @@ export { PlayableDirector } from "../timeline/PlayableDirector.js";
 export { SignalAsset } from "../timeline/SignalAsset.js";
 export { SignalReceiverEvent } from "../timeline/SignalAsset.js";
 export { SignalReceiver } from "../timeline/SignalAsset.js";
-export { AnimationTrackHandler } from "../timeline/TimelineTracks.js";
-export { AudioTrackHandler } from "../timeline/TimelineTracks.js";
-export { MarkerTrackHandler } from "../timeline/TimelineTracks.js";
+export { TimelineBuilder } from "../timeline/TimelineBuilder.js";
+export { TimelineAnimationTrack } from "../timeline/TimelineTracks.js";
+export { TimelineAudioTrack } from "../timeline/TimelineTracks.js";
+export { TimelineMarkerTrack } from "../timeline/TimelineTracks.js";
 export { SignalTrackHandler } from "../timeline/TimelineTracks.js";
-export { ControlTrackHandler } from "../timeline/TimelineTracks.js";
+export { TimelineActivationTrack } from "../timeline/TimelineTracks.js";
+export { TimelineControlTrack } from "../timeline/TimelineTracks.js";
 export { TransformGizmo } from "../TransformGizmo.js";
 export { BaseUIComponent } from "../ui/BaseUIComponent.js";
 export { UIRootComponent } from "../ui/BaseUIComponent.js";

package/src/engine-components/postprocessing/VolumeParameter.ts

@@ -156,4 +156,7 @@ class VolumeParameterSerializer extends TypeSerializer {
         return parameter;
     }
 }
-new VolumeParameterSerializer();
+/** @internal */
+export function initVolumeParameterSerializer() {
+    new VolumeParameterSerializer();
+}