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

package/src/engine/webcomponents/needle menu/needle-menu.ts

@@ -1,6 +1,6 @@
 import { showBalloonMessage } from "../../debug/debug.js";
 import type { Context } from "../../engine_context.js";
-import { _imGyfK, $ECTXQRP, Telemetry } from "../../engine_license.js";
+import { $fwGZrGe, $BWnhWzrW, Telemetry } from "../../engine_license.js";
 import { isLocalNetwork } from "../../engine_networking_utils.js";
 import { HTMLElementBase } from "../../engine_ssr.js";
 import { DeviceUtilities, getParam } from "../../engine_utils.js";
@@ -778,8 +778,8 @@ export class NeedleMenuElement extends HTMLElementBase {
         try {
             // if the user has a license then we CAN hide the needle logo
             // calling this method immediately will cause an issue with vite bundling tho
-            window.requestAnimationFrame(() => $ECTXQRP(res => {
-                if (res == true && _imGyfK() && !debugNonCommercial) {
+            window.requestAnimationFrame(() => $BWnhWzrW(res => {
+                if (res == true && $fwGZrGe() && !debugNonCommercial) {
                     let visible = this._userRequestedLogoVisible;
                     if (visible === undefined) visible = false;
                     this.___onSetLogoVisible(visible);
@@ -830,7 +830,7 @@ export class NeedleMenuElement extends HTMLElementBase {
                 // ensure the menu is not hidden or removed
                 const requiredParent = this?.parentNode;
                 if (this.style.display != "flex" || this.style.visibility != "visible" || this.style.opacity != "1" || requiredParent != this._domElement?.shadowRoot) {
-                    if (!_imGyfK()) {
+                    if (!$fwGZrGe()) {
                         const change = changeEventCounter++;
                         // if a user doesn't have a local pro license *but* for development the menu is hidden then we show a warning
                         if (isLocalNetwork() && this._userRequestedMenuVisible === false) {
@@ -918,7 +918,7 @@ export class NeedleMenuElement extends HTMLElementBase {
     showNeedleLogo(visible: boolean) {
         this._userRequestedLogoVisible = visible;
         if (!visible) {
-            if (!_imGyfK() || debugNonCommercial) {
+            if (!$fwGZrGe() || debugNonCommercial) {
                 console.warn("[Needle Engine] You need a PRO license to hide the Needle Engine logo in production.");
                 const localNetwork = isLocalNetwork()
                 if (!localNetwork) return;

package/src/engine/webcomponents/needle-engine.loading.ts

@@ -1,6 +1,6 @@
 import { needleLogoOnlySVG } from "../assets/index.js"
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
-import { _imGyfK, rkHTARX, $hQhmn } from "../engine_license.js";
+import { $fwGZrGe, _XtEQ, ICD } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { LoadingProgressArgs } from "../engine_setup.js";
 import { getParam } from "../engine_utils.js";
@@ -205,7 +205,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
         }
 
 
-        const hasLicense = rkHTARX();
+        const hasLicense = _XtEQ();
         if (!existing) {
             this._loadingElement.style.position = "absolute";
             this._loadingElement.style.width = "100%";
@@ -373,7 +373,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
 
     // private async handleRuntimeLicense(loadingElement: HTMLElement) {
     //     // First check if we have a commercial license
-    //     let commercialLicense = _imGyfK();
+    //     let commercialLicense = $fwGZrGe();
     //     // if it's the case then we don't need to perform a runtime check
     //     if (commercialLicense) return;
 
@@ -393,10 +393,10 @@ export class EngineLoadingView implements ILoadingViewHandler {
     //     loadingElement.appendChild(nonCommercialContainer);
 
     //     // Use the runtime license check
-    //     if (!isDevEnvironment() && $hQhmn) {
+    //     if (!isDevEnvironment() && ICD) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await $hQhmn;
-    //         commercialLicense = _imGyfK();
+    //         await ICD;
+    //         commercialLicense = $fwGZrGe();
     //     }
     //     if (commercialLicense) return;
     //     nonCommercialContainer.style.transition = "opacity .5s ease-in-out";

package/src/engine/webcomponents/needle-engine.ts

@@ -3,7 +3,7 @@ import type { Texture } from "three";
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
-import { _imGyfK } from "../engine_license.js";
+import { $fwGZrGe } from "../engine_license.js";
 import { onStart } from "../engine_lifecycle_api.js";
 import { setDracoDecoderPath, setDracoDecoderType, setKtx2TranscoderPath } from "../engine_loaders.gltf.js";
 import { Context, ContextCreateArgs } from "../engine_setup.js";
@@ -579,7 +579,7 @@ export class NeedleEngineWebComponent extends HTMLElementBase implements INeedle
 
 
         // Loading start events
-        const allowOverridingDefaultLoading = _imGyfK();
+        const allowOverridingDefaultLoading = $fwGZrGe();
         // default loading can be overriden by calling preventDefault in the onload start event
         this.ensureLoadStartIsRegistered();
         let useDefaultLoading = this.dispatchEvent(new CustomEvent("loadstart", {

package/src/engine/xr/TempXRContext.ts

@@ -3,7 +3,7 @@ import { ArrayCamera, AxesHelper, Camera, Color, DirectionalLight, Fog, GridHelp
 import { needleLogoOnlySVG } from "../assets/index.js";
 import { isDevEnvironment } from "../debug/index.js";
 import { ObjectUtils, PrimitiveType } from "../engine_create_objects.js";
-import { _imGyfK } from "../engine_license.js";
+import { $fwGZrGe } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { delay, DeviceUtilities } from "../engine_utils.js";
 
@@ -215,7 +215,7 @@ export class TemporaryXRContext {
         this._scene.background = new Color(0x000000);
 
         let logoSrc = needleLogoOnlySVG;
-        if (_imGyfK()) {
+        if ($fwGZrGe()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");

package/src/engine-components/Component.ts

@@ -1107,7 +1107,8 @@ export abstract class Component implements IComponent, EventTarget,
         this.__didCompleteStart = false;
         this.__inEnableOrDisableCallback = false;
         this.__didEnable = false;
-        this.__isEnabled = undefined;
+        // Preserve copied/constructor-assigned enabled state while resetting lifecycle flags.
+        // Cloned disabled components must not fall back to the default enabled=true state.
         this.__destroyed = false;
         this._internalInit(init);
         return this;

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;
@@ -826,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
@@ -839,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);
@@ -851,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) {
@@ -861,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/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 { rkHTARX } 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 (!rkHTARX()) {
+        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 (!rkHTARX()) {
+                        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 (!rkHTARX()) {
+        if (!_XtEQ()) {
             console.log("Custom Quicklook banner text requires pro license: https://needle.tools/pricing");
             obj.callToAction = "Close";
             obj.checkoutTitle = "🌵 Made with Needle";