@needle-tools/engine 5.1.0-alpha.8 → 5.1.0-beta

package/src/engine-components/DragControlsConstraints.ts

@@ -163,6 +163,8 @@ export class KeepScaleConstraint implements IDragConstraint {
  * new ScaleLimitConstraint(0.01, 10000, true, object.worldScale.clone());
  * ```
  */
+const _scaleLimitWs = new Vector3();
+
 export class ScaleLimitConstraint implements IDragConstraint {
     /**
      * @param min                    Lower bound. Relative mode: fraction of initial scale. Raw mode: absolute world-scale per axis.
@@ -184,27 +186,33 @@ export class ScaleLimitConstraint implements IDragConstraint {
     }
 
     apply(followObject: GameObject): void {
-        const ws = followObject.worldScale;
+        // Read world scale directly from the matrix columns (col 0/1/2 lengths) rather than
+        // going through the worldScale getter, which internally calls updateWorldMatrix() again.
+        // We call it once here so the matrix is fresh, then read the elements directly.
+        const obj = followObject as unknown as Object3D;
+        obj.updateWorldMatrix(true, false);
+        const e = obj.matrixWorld.elements;
+        const sx = Math.sqrt(e[0] * e[0] + e[1] * e[1] + e[2] * e[2]);
+        const sy = Math.sqrt(e[4] * e[4] + e[5] * e[5] + e[6] * e[6]);
+        const sz = Math.sqrt(e[8] * e[8] + e[9] * e[9] + e[10] * e[10]);
+        _scaleLimitWs.set(sx, sy, sz);
+        const ws = _scaleLimitWs;
+
         if (this.relativeToInitialScale) {
-            // Derive the uniform scale ratio from the magnitude of the current world scale
-            // relative to the initial world scale magnitude.
             const initLen = this._initialWorldScale.length();
             if (initLen < 1e-10) return;
             const ratio = ws.length() / initLen;
             const clamped = Math.max(this.min, Math.min(this.max, ratio));
             if (Math.abs(clamped - ratio) > 1e-9) {
-                ws.copy(this._initialWorldScale).multiplyScalar(clamped);
-                followObject.worldScale = ws;
+                followObject.worldScale = ws.copy(this._initialWorldScale).multiplyScalar(clamped);
                 followObject.updateMatrix();
             }
         } else {
-            // Absolute per-axis clamp.
             const cx = Math.max(this.min, Math.min(this.max, ws.x));
             const cy = Math.max(this.min, Math.min(this.max, ws.y));
             const cz = Math.max(this.min, Math.min(this.max, ws.z));
             if (cx !== ws.x || cy !== ws.y || cz !== ws.z) {
-                ws.set(cx, cy, cz);
-                followObject.worldScale = ws;
+                followObject.worldScale = ws.set(cx, cy, cz);
                 followObject.updateMatrix();
             }
         }

package/src/engine-components/EventList.ts

@@ -56,7 +56,7 @@ export class CallInfo {
                 if (args !== undefined && args.length > 0)
                     argumentsBuffer.push(...args);
                 argumentsBuffer.push(...this.arguments);
-                this.target(...this.arguments);
+                this.target(...argumentsBuffer);
                 argumentsBuffer.length = 0;
             }
             else {

package/src/engine-components/SceneSwitcher.ts

@@ -614,7 +614,8 @@ export class SceneSwitcher extends Behaviour {
         this._currentScene = undefined;
         if (current) {
             if (debug) console.log("[SceneSwitcher] UNLOAD", current.url, "HasURL?: " + current.hasUrl)
-            const sceneListener = this.tryGetSceneEventListener(current.asset as any as Object3D);
+            const activeSceneInstance = this._currentSceneAsset;
+            const sceneListener = this.tryGetSceneEventListener(activeSceneInstance as any as Object3D);
             if (sceneListener?.sceneClosing) {
                 const res = sceneListener.sceneClosing();
                 if (res instanceof Promise) await res;
@@ -624,20 +625,24 @@ export class SceneSwitcher extends Behaviour {
             // // then we unload it
             if (current.hasUrl) {
                 current.unload();
-                if (this._currentSceneAsset) destroy(this._currentSceneAsset, true, false);
+                if (activeSceneInstance) destroy(activeSceneInstance, true, false);
             }
             else {
-                GameObject.remove(this._currentSceneAsset);
+                GameObject.remove(activeSceneInstance);
             }
+            this._currentSceneAsset = undefined;
         }
     }
 
     private _currentlyLoadingScene?: AssetReference;
+    private _loadingRequestId: number = 0;
+    private _activeLoadingRequestId: number = 0;
     /** @internal */
     private async __internalSwitchScene(scene: AssetReference): Promise<boolean> {
 
         await this.__unloadCurrentScene();
         const index = this._currentIndex = this.scenes?.indexOf(scene) ?? -1;
+        const loadingRequestId = ++this._loadingRequestId;
 
         try {
             if (debug) console.debug(`${Date.now()} [SceneSwitcher] Loading scene start: ${scene.url} (index: ${index})`);
@@ -647,9 +652,10 @@ export class SceneSwitcher extends Behaviour {
             const loadStartEvt = new CustomEvent<LoadSceneEvent>("loadscene-start", { detail: { scene: scene, switcher: this, index: index } })
             this.dispatchEvent(loadStartEvt);
             this.sceneLoadingStart?.invoke(loadStartEvt.detail);
-            await this.onStartLoading();
+            await this.onStartLoading(loadingRequestId);
             // start loading and wait for the scene to be loaded
             await scene.loadAssetAsync((_, prog) => {
+                if (loadingRequestId !== this._activeLoadingRequestId) return;
                 if (debug) {
                     const t01 = prog.loaded / prog.total;
                     const progressBarString = "[" + "=".repeat(Math.floor(t01 * 20)) + "-".repeat(20 - Math.floor(t01 * 20)) + "]";
@@ -659,12 +665,14 @@ export class SceneSwitcher extends Behaviour {
                 this.dispatchEvent(prog);
                 this.sceneLoadingProgress?.invoke(prog);
             }).catch(console.error);
-            await this.onEndLoading();
+            await this.onEndLoading(loadingRequestId);
             const finishedEvt = new CustomEvent<LoadSceneEvent>("loadscene-finished", { detail: { scene: scene, switcher: this, index: index } });
             this.dispatchEvent(finishedEvt);
 
-            this._currentLoadingProgress = undefined;
-            this._currentlyLoadingScene = undefined;
+            if (loadingRequestId === this._activeLoadingRequestId) {
+                this._currentLoadingProgress = undefined;
+                this._currentlyLoadingScene = undefined;
+            }
 
             if (finishedEvt.defaultPrevented) {
                 if (debug) console.warn("[SceneSwitcher] Adding loaded scene prevented:", scene, finishedEvt);
@@ -737,8 +745,8 @@ export class SceneSwitcher extends Behaviour {
                             history.pushState(stateName, "unused", location.href);
                     }
                 }
-                // Call SceneListener opened callback (if a SceneListener is in the scene)
-                const sceneListener = this.tryGetSceneEventListener(scene.asset as any as Object3D);
+                // Call SceneListener opened callback on the scene instance that was actually added.
+                const sceneListener = this.tryGetSceneEventListener(this._currentSceneAsset as any as Object3D);
                 if (sceneListener?.sceneOpened) {
                     const res = sceneListener.sceneOpened(this);
                     if (res instanceof Promise) await res;
@@ -791,8 +799,20 @@ export class SceneSwitcher extends Behaviour {
                 for (let i = 0; i < this.scenes.length; i++) {
                     const scene = this.scenes[i];
                     if (!scene) continue;
-                    const name = scene instanceof Object3D ? scene.name : sceneUriToName(scene.url);
-                    if (name.toLowerCase().includes(lowerCaseValue)) {
+                    // Match against the url-derived name AND, for in-scene object
+                    // references (which have an empty url), the referenced object's
+                    // name. Without the latter, `?scene=<name>` never resolves for
+                    // non-prefab/object scenes and the switcher falls back to the
+                    // default scene (scenes is AssetReference[], so the
+                    // `scene instanceof Object3D` branch alone never matched them).
+                    const candidateNames: string[] = [];
+                    if (scene instanceof Object3D) candidateNames.push(scene.name);
+                    else {
+                        if (scene.url) candidateNames.push(sceneUriToName(scene.url));
+                        const asset = scene.asset;
+                        if (asset instanceof Object3D && asset.name) candidateNames.push(asset.name);
+                    }
+                    if (candidateNames.some(n => n?.toLowerCase().includes(lowerCaseValue))) {
                         return this.select(i);
                     }
                 }
@@ -814,7 +834,8 @@ export class SceneSwitcher extends Behaviour {
     private _isCurrentlyLoading: boolean = false;
     private _currentLoadingProgress: ProgressEvent | undefined = undefined;
 
-    private async onStartLoading() {
+    private async onStartLoading(loadingRequestId: number) {
+        this._activeLoadingRequestId = loadingRequestId;
         this._isCurrentlyLoading = true;
         if (this.loadingScene) {
             // save the last loading scene reference so that it can be changed at runtime
@@ -827,7 +848,7 @@ export class SceneSwitcher extends Behaviour {
                 this._loadingScenePromise = this.loadingScene?.loadAssetAsync().then(res => res != null);
             }
             await this._loadingScenePromise;
-            if (this._isCurrentlyLoading && this.loadingScene?.asset) {
+            if (loadingRequestId === this._activeLoadingRequestId && this._isCurrentlyLoading && this.loadingScene?.asset) {
                 if (debug) console.log("Add loading scene", this.loadingScene.url, this.loadingScene.asset)
                 const loadingScene = this.loadingScene.asset as any as Object3D;
                 GameObject.add(loadingScene, this.gameObject);
@@ -839,7 +860,7 @@ export class SceneSwitcher extends Behaviour {
             }
         }
         // Invoke the event on a loading listener on the same object as the scene switcher
-        if (this._isCurrentlyLoading) {
+        if (loadingRequestId === this._activeLoadingRequestId && this._isCurrentlyLoading) {
             const listener = this.tryGetSceneEventListener(this.gameObject);
             if (listener) {
                 if (listener.sceneOpened) {
@@ -849,7 +870,8 @@ export class SceneSwitcher extends Behaviour {
             }
         }
     }
-    private async onEndLoading() {
+    private async onEndLoading(loadingRequestId: number) {
+        if (loadingRequestId !== this._activeLoadingRequestId) return;
         this._isCurrentlyLoading = false;
         if (this.loadingScene?.asset) {
             if (debug) console.log("Remove loading scene", this.loadingScene.url);

package/src/engine-components/SeeThrough.ts

@@ -11,7 +11,7 @@ import { Behaviour } from "./Component.js";
 import { IUSDExporterExtension } from "./export/usdz/Extension.js";
 import { USDZExporter } from "./export/usdz/USDZExporter.js";
 import type { OrbitControls } from "./OrbitControls.js";
-import { Renderer } from "./Renderer.js";
+import { Renderer, ShadowCastingMode } from "./Renderer.js";
 
 const debugSeeThrough = getParam("debugseethrough");
 
@@ -164,6 +164,35 @@ export class SeeThrough extends Behaviour {
     @serializable()
     autoUpdate: boolean = true;
 
+    /**
+     * The alpha (opacity) the object is currently faded to, in the `[0, 1]` range.
+     * `1` means fully visible, `0` means fully hidden. This is the live, animated value
+     * (it lerps toward the target over {@link fadeDuration}), updated every frame the fade runs.
+     *
+     * External components can read this to react to the see-through state — e.g. toggling a
+     * collider, muting audio, or driving a UI prompt as the object fades in or out.
+     *
+     * @example React to the object becoming (almost) hidden
+     * ```ts
+     * if (seeThrough.currentAlpha < 0.1) {
+     *   // object is essentially see-through now
+     * }
+     * ```
+     * @default 1
+     */
+    get currentAlpha(): number {
+        return this._currentAlpha;
+    }
+
+
+    /**
+     * Below this alpha the object stops casting a shadow. The shadow map only stores depth, so a
+     * faded object would otherwise keep casting a fully solid shadow (three.js does not fade shadows
+     * by opacity). Toggling shadow casting off near-invisible is the cleanest fix; we drive it via
+     * the {@link Renderer.shadowCastingMode} so it cooperates with the per-frame shadow settings the
+     * Renderer re-applies. Note this is a hard on/off, not a fade.
+     */
+    public static readonly shadowHideThreshold = 0.05;
 
     private readonly _referencePointVector: Vector3 = new Vector3();
     private readonly _referencePointDir: Vector3 = new Vector3();
@@ -171,6 +200,9 @@ export class SeeThrough extends Behaviour {
     private _renderer: Renderer[] | null = null;
     private _needsUpdate = true;
     private _id = i++;
+    private _currentAlpha: number = 1;
+    /** Renderers whose shadow casting we turned off while hidden, mapped to their original mode for restore. */
+    private readonly _suppressedShadowCasting = new Map<Renderer, ShadowCastingMode>();
 
     /** * @internal */
     onEnable() {
@@ -178,6 +210,12 @@ export class SeeThrough extends Behaviour {
         this._renderer = null;
     }
 
+    /** @internal */
+    onDestroy() {
+        // Don't leave renderers permanently non-casting if this component is removed.
+        this.restoreSuppressedShadowCasting();
+    }
+
     /**
      * @internal
      */
@@ -258,13 +296,49 @@ export class SeeThrough extends Behaviour {
             if (newAlpha >= 0.99) newAlpha = 1;
             else if (newAlpha <= 0.01) newAlpha = 0;
 
+            // Expose the live fade value so external components can react to it (see `currentAlpha`).
+            // Renderers are driven by the same target/duration, so the last applied value is representative.
+            this._currentAlpha = newAlpha;
+
             // const currentTransparent = (block.getOverride("transparent")?.value ?? materials[0].transparent ?? false) as boolean;
 
             block.setOverride("alphaHash", this.useAlphaHash);
             block.setOverride("opacity", newAlpha);
             block.setOverride("transparent", newAlpha >= 0.99999 ? false : !this.useAlphaHash);
+
+            // Stop casting a shadow once the object is essentially invisible (and restore it when it
+            // comes back). A faded object otherwise keeps a fully solid shadow — see shadowHideThreshold.
+            this.updateShadowCasting(renderer, newAlpha);
         });
     }
 
+    /**
+     * Suppress or restore a renderer's shadow casting based on its current alpha.
+     * Driving {@link Renderer.shadowCastingMode} (rather than the raw `mesh.castShadow`) is required
+     * because the Renderer re-applies that setting every frame; we remember the original mode so it
+     * is restored exactly when the object fades back in.
+     */
+    private updateShadowCasting(renderer: Renderer, alpha: number) {
+        const shouldHideShadow = alpha < SeeThrough.shadowHideThreshold;
+        if (shouldHideShadow) {
+            if (renderer.shadowCastingMode !== ShadowCastingMode.Off) {
+                this._suppressedShadowCasting.set(renderer, renderer.shadowCastingMode);
+                renderer.shadowCastingMode = ShadowCastingMode.Off;
+            }
+        }
+        else if (this._suppressedShadowCasting.has(renderer)) {
+            renderer.shadowCastingMode = this._suppressedShadowCasting.get(renderer)!;
+            this._suppressedShadowCasting.delete(renderer);
+        }
+    }
+
+    /** Restore every renderer we suppressed shadow casting on, then clear the bookkeeping. */
+    private restoreSuppressedShadowCasting() {
+        for (const [renderer, mode] of this._suppressedShadowCasting) {
+            if (!renderer.destroyed) renderer.shadowCastingMode = mode;
+        }
+        this._suppressedShadowCasting.clear();
+    }
+
 }
 

package/src/engine-components/api.ts

@@ -44,6 +44,7 @@ export { Behaviour, Component, GameObject } from "./Component.js";
 export { AudioRolloffMode } from "./AudioSource.js";
 export { ClearFlags } from "./Camera.js"
 export { DragMode } from "./DragControls.js";
+export { ShadowCastingMode, ReflectionProbeUsage } from "./Renderer.js";
 export type { DropListenerNetworkEventArguments, DropListenerOnDropArguments } from "./DropListener.js";
 export * from "./export/index.js"
 export * from "./particlesystem/api.js"

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

@@ -25,7 +25,17 @@ export { LogStats } from "../debug/LogStats.js";
 export { DeleteBox } from "../DeleteBox.js";
 export { Deletable } from "../DeleteBox.js";
 export { DeviceFlag } from "../DeviceFlag.js";
+export { DragProfile } from "../DragControls.js";
 export { DragControls } from "../DragControls.js";
+export { GridSnapConstraint } from "../DragControlsConstraints.js";
+export { GrabPointPlaneConstraint } from "../DragControlsConstraints.js";
+export { KeepRotationConstraint } from "../DragControlsConstraints.js";
+export { KeepScaleConstraint } from "../DragControlsConstraints.js";
+export { ScaleLimitConstraint } from "../DragControlsConstraints.js";
+export { FixedRotationAxesConstraint } from "../DragControlsConstraints.js";
+export { AxisRotationConstraint } from "../DragControlsConstraints.js";
+export { PlaneHeightLockConstraint } from "../DragControlsConstraints.js";
+export { SnapToSurfaceConstraint } from "../DragControlsConstraints.js";
 export { DropListener } from "../DropListener.js";
 export { Duplicatable } from "../Duplicatable.js";
 export { CallInfo } from "../EventList.js";

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -3,7 +3,7 @@ import { Euler, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "t
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { findObjectOfType } from "../../../engine/engine_components.js";
-import { _$QyV } from "../../../engine/engine_license.js";
+import { _XtEQ } from "../../../engine/engine_license.js";
 import { serializable } from "../../../engine/engine_serialization.js";
 import { getFormattedDate, Progress } from "../../../engine/engine_time_utils.js";
 import { DeviceUtilities, getParam } from "../../../engine/engine_utils.js";
@@ -277,7 +277,7 @@ export class USDZExporter extends Behaviour {
         let name = this.exportFileName ?? this.objectToExport?.name ?? this.name;
         name += "-" + getFormattedDate(); // seems iOS caches the file in some cases, this ensures we always have a fresh file
 
-        if (!_$QyV()) {
+        if (!_XtEQ()) {
             if (name !== "") name += "-";
             name += "MadeWithNeedle";
         }
@@ -682,7 +682,7 @@ export class USDZExporter extends Behaviour {
                     if (debug)
                         showBalloonMessage("Quicklook url: " + callToActionURL);
                     if (callToActionURL) {
-                        if (!_$QyV()) {
+                        if (!_XtEQ()) {
                             console.warn("Quicklook closed: custom redirects require a Needle Engine Pro license: https://needle.tools/pricing", callToActionURL)
                         }
                         else {
@@ -697,7 +697,7 @@ export class USDZExporter extends Behaviour {
     private buildQuicklookOverlay(): CustomBranding {
         const obj: CustomBranding = {};
         if (this.customBranding) Object.assign(obj, this.customBranding);
-        if (!_$QyV()) {
+        if (!_XtEQ()) {
             console.log("Custom Quicklook banner text requires pro license: https://needle.tools/pricing");
             obj.callToAction = "Close";
             obj.checkoutTitle = "🌵 Made with Needle";

package/src/engine-components/timeline/PlayableDirector.ts

@@ -222,7 +222,7 @@ export class PlayableDirector extends Behaviour {
 
     /** @internal */
     onEnable() {
-        if (debug) console.log("[Timeline] OnEnable", this.name, this.playOnAwake);
+        if (debug) console.log("[Timeline] OnEnable", { name: this.name, playOnAwake: this.playOnAwake });
 
         for (const tracks of this._allTracks) {
             for (const track of tracks) {