@needle-tools/engine 5.1.0-next.1780579670.dramatic-pierogi.b8fa941 → 5.1.0

package/src/engine/xr/init.ts

@@ -12,9 +12,8 @@ export function initXR() {
 
     if (DeviceUtilities.isiOS()) {
 
-        // Prefetch
-        const url = new URL("https://appclip.apple.com/id?p=tools.needle.launch-app.Clip");
-        url.searchParams.set("url", location.href);
+        // Prefetch (uses the custom branded AppClip experience if NeedleXRSession.appClipUrl is set, otherwise the default Needle AppClip)
+        const url = NeedleXRSession.getAppClipLaunchUrl();
         const urlStr = url.toString();
         fetch(urlStr, { method: "HEAD", mode: "no-cors" }).catch(() => {
             // appclip prefetch - to get metadata faster on iOS devices, this seems to fix the double tap issue when opening the appclip for AR sessions.

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;
@@ -1165,6 +1166,17 @@ export abstract class Component implements IComponent, EventTarget,
         }
         this.__didEnable = true;
         this.__isEnabled = true;
+        // Enforce "enabled + not-yet-started ⇒ queued for start". A component can be
+        // re-enabled before it ever started — e.g. removed from the scene (which
+        // strips it from new_script_start via processRemoveFromScene) and then
+        // re-activated through a path other than GameObject.add (raw scene re-add +
+        // setActive, a parent activeInHierarchy flip, …). Those paths re-run onEnable
+        // but never re-enqueue start, leaving the component enabled+active but with
+        // start() never called. Re-queue it here so processStart picks it up.
+        if (!this.__didStart) {
+            const startQueue = this.context?.new_script_start;
+            if (startQueue && !startQueue.includes(this)) startQueue.push(this);
+        }
         this.__inEnableOrDisableCallback = true;
         this.onEnable();
         this.__inEnableOrDisableCallback = false;

package/src/engine-components/ContactShadows.ts

@@ -83,7 +83,7 @@ type FitParameters = {
  */
 export class ContactShadows extends Behaviour {
 
-    private static readonly _instances: Map<Context, ContactShadows> = new Map();
+    private static readonly _instances: WeakMap<Context, ContactShadows> = new WeakMap();
     /**
      * Create contact shadows for the scene. Automatically fits the shadows to the scene.  
      * The instance of contact shadows will be created only once.  
@@ -179,8 +179,9 @@ export class ContactShadows extends Behaviour {
      * in which case ContactShadows scale would affect the projection
      **/
     private readonly shadowsRoot: IGameObject = new Object3D() as IGameObject;
-    private shadowCamera?: OrthographicCamera;
     private readonly shadowGroup: Group = new Group();
+    
+    private shadowCamera?: OrthographicCamera;
 
     private renderTarget?: WebGLRenderTarget;
     private renderTargetBlur?: WebGLRenderTarget;
@@ -240,19 +241,86 @@ export class ContactShadows extends Behaviour {
         if (debug) console.log("Fitted shadows to scene", this.shadowsRoot.scale.clone());
     }
 
+    /**
+     * Call to update the shadows immediately. Only needed if `manualUpdate` is enabled, usually the shadows will update automatically when the scene changes or when the component is enabled.
+     */
+    renderShadowsNow() {
+        this._renderShadows();
+    }
 
     /** @internal */
     awake() {
         ContactShadows._instances.set(this.context, this);
-        this.shadowsRoot.hideFlags = HideFlags.DontExport;
+    }
 
+    /** @internal */
+    onEnable(): void {
+        this.shadowsRoot.hideFlags = HideFlags.DontExport;
         // ignore self for autofitting
         setAutoFitEnabled(this.shadowsRoot, false);
+
+        this._needsUpdate = true;
+        this.autoCleanup(this.context.events.on("scene-content-changed", () => {
+            if (!this.autoFit) return;
+            this._needsFit = true;
+            this._needsUpdate = true;
+        }));
+
+        if (this.autoFit) this.fitShadows();
+        else this.applyMinSize();
     }
 
+    /** @internal */
+    onDestroy(): void {
+        if (debug) console.warn("Destroying ContactShadows on " + this.gameObject.name);
+
+        const instance = ContactShadows._instances.get(this.context);
+        if (instance === this) {
+            ContactShadows._instances.delete(this.context);
+        }
+
+        // dispose the render targets
+        this.renderTarget?.dispose();
+        this.renderTargetBlur?.dispose();
+
+        // dispose the materials
+        this.depthMaterial?.dispose();
+        this.horizontalBlurMaterial?.dispose();
+        this.verticalBlurMaterial?.dispose();
+
+        // dispose the geometries
+        this.blurPlane?.geometry.dispose();
+        this.plane?.geometry.dispose();
+        this.occluderMesh?.geometry.dispose();
+    }
 
     /** @internal */
-    start(): void {
+    onBeforeRender(_frame: XRFrame | null): void {
+
+        if (this._needsFit && this.autoFit) {
+            this._needsFit = false;
+            this.fitShadows();
+        }
+
+        if (this.manualUpdate) {
+            if (!this._needsUpdate) return;
+        }
+        this._needsUpdate = false;
+        this._renderShadows();
+    }
+
+    private _ensureSetup() {
+
+        // Make sure the shadows root is parented to the game object. This is needed for the shadows to be in the correct position and scale relative to the game object. We need to do this before checking if the materials are set up because some properties (e.g. darkness) can be changed in the editor before the component is enabled, so we want to avoid re-creating everything in that case.
+        if (this.shadowsRoot.parent !== this.gameObject) {
+            this.gameObject.add(this.shadowsRoot);
+        }
+
+        // Check if everything is already set up. We need to do this because some properties (e.g. darkness) can be changed in the editor before the component is enabled, so we want to avoid re-creating everything in that case.
+        if (this.depthMaterial && this.horizontalBlurMaterial && this.verticalBlurMaterial && this.planeMaterial) {
+            return;
+        }
+
         if (debug) console.log("Create ContactShadows on " + this.gameObject.name, this)
 
         this.gameObject.add(this.shadowsRoot);
@@ -363,54 +431,11 @@ export class ContactShadows extends Behaviour {
         this.verticalBlurMaterial.depthTest = false;
 
         this.shadowGroup.visible = false;
-
-        if (this.autoFit) this.fitShadows();
-        else this.applyMinSize();
     }
 
-    onEnable(): void {
-        this._needsUpdate = true;
-        this.autoCleanup(this.context.events.on("scene-content-changed", () => {
-            if (!this.autoFit) return;
-            this._needsFit = true;
-            this._needsUpdate = true;
-        }));
-    }
+    private _renderShadows() {
 
-    /** @internal */
-    onDestroy(): void {
-        const instance = ContactShadows._instances.get(this.context);
-        if (instance === this) {
-            ContactShadows._instances.delete(this.context);
-        }
-
-        // dispose the render targets
-        this.renderTarget?.dispose();
-        this.renderTargetBlur?.dispose();
-
-        // dispose the materials
-        this.depthMaterial?.dispose();
-        this.horizontalBlurMaterial?.dispose();
-        this.verticalBlurMaterial?.dispose();
-
-        // dispose the geometries
-        this.blurPlane?.geometry.dispose();
-        this.plane?.geometry.dispose();
-        this.occluderMesh?.geometry.dispose();
-    }
-
-    /** @internal */
-    onBeforeRender(_frame: XRFrame | null): void {
-
-        if (this._needsFit && this.autoFit) {
-            this._needsFit = false;
-            this.fitShadows();
-        }
-
-        if (this.manualUpdate) {
-            if (!this._needsUpdate) return;
-        }
-        this._needsUpdate = false;
+        this._ensureSetup();
 
         if (!this.renderTarget || !this.renderTargetBlur ||
             !this.depthMaterial || !this.shadowCamera ||
@@ -536,6 +561,7 @@ export class ContactShadows extends Behaviour {
         scene.background = initialBackground;
         renderer.xr.enabled = prevXRState;
         this.context.scene.matrixWorldAutoUpdate = prevSceneMatrixAutoUpdate;
+
     }
 
     // renderTarget --> blurPlane (horizontalBlur) --> renderTargetBlur --> blurPlane (verticalBlur) --> renderTarget

package/src/engine-components/GroundProjection.ts

@@ -1,4 +1,4 @@
-import { CubeUVReflectionMapping, ShaderMaterial, Texture } from "three";
+import { CubeUVReflectionMapping, Euler, Matrix3, Matrix4, ShaderMaterial, Texture } from "three";
 import { GroundedSkybox as GroundProjection } from 'three/examples/jsm/objects/GroundedSkybox.js';
 
 import { Gizmos } from "../engine/engine_gizmos.js";
@@ -21,8 +21,13 @@ type GroundProjectionShaderUniforms = {
     needleGroundProjectionBlending: { value: number };
     needleGroundProjectionAlphaFactor: { value: number };
     needleGroundProjectionBackgroundIntensity: { value: number };
+    needleGroundProjectionBackgroundRotation: { value: Matrix3 };
 };
 
+// Reused per-frame to build the background-rotation matrix without allocating in onBeforeRender.
+const _backgroundRotationEuler = new Euler();
+const _backgroundRotationMatrix = new Matrix4();
+
 const needleCubeUvMapVarying = /* glsl */`
 #ifdef NEEDLE_USE_CUBE_UV_MAP
 varying vec3 vNeedleGroundProjectionWorldDirection;
@@ -79,7 +84,10 @@ const needleCubeUvMapFragment = /* glsl */`
 
     #endif
 
-    sampledDiffuseColor.rgb *= mix(1.0, needleGroundProjectionBackgroundIntensity, needleGroundProjectionBlurFactorValue);
+    // Apply backgroundIntensity uniformly across the whole projection (center included), matching how the
+    // skybox applies it (backgroundCube.glsl: texColor.rgb *= backgroundIntensity). Only the blurriness
+    // ramps toward the horizon - the intensity must not.
+    sampledDiffuseColor.rgb *= needleGroundProjectionBackgroundIntensity;
     diffuseColor *= sampledDiffuseColor;
 
 #endif
@@ -122,7 +130,8 @@ function getGroundProjectionShaderUniforms(material: GroundProjectionMaterial):
         needleGroundProjectionBlurriness: { value: 0 },
         needleGroundProjectionBlending: { value: 0 },
         needleGroundProjectionAlphaFactor: { value: 1 },
-        needleGroundProjectionBackgroundIntensity: { value: 1 }
+        needleGroundProjectionBackgroundIntensity: { value: 1 },
+        needleGroundProjectionBackgroundRotation: { value: new Matrix3() }
     };
 }
 
@@ -133,15 +142,25 @@ function configureGroundProjectionMaterial(material: GroundProjectionMaterial, t
         shader.uniforms.needleGroundProjectionBlending = projectionUniforms.needleGroundProjectionBlending;
         shader.uniforms.needleGroundProjectionAlphaFactor = projectionUniforms.needleGroundProjectionAlphaFactor;
         shader.uniforms.needleGroundProjectionBackgroundIntensity = projectionUniforms.needleGroundProjectionBackgroundIntensity;
+        shader.uniforms.needleGroundProjectionBackgroundRotation = projectionUniforms.needleGroundProjectionBackgroundRotation;
 
         shader.vertexShader = shader.vertexShader
-            .replace("#include <uv_pars_vertex>", `#include <uv_pars_vertex>\n${needleCubeUvMapVarying}`)
+            .replace("#include <uv_pars_vertex>", `#include <uv_pars_vertex>\n${needleCubeUvMapVarying}
+#ifdef NEEDLE_USE_CUBE_UV_MAP
+uniform mat3 needleGroundProjectionBackgroundRotation;
+#endif`)
             .replace(
                 "#include <worldpos_vertex>",
                 `#include <worldpos_vertex>
 #ifdef NEEDLE_USE_CUBE_UV_MAP
-	// GroundedSkybox mirrors geometry on Z, so undo that before deriving the sampling direction.
-	vNeedleGroundProjectionWorldDirection = transformDirection( vec3( position.x, position.y, -position.z ), modelMatrix );
+	// Sample the environment in the fragment's actual world direction. GroundedSkybox mirrors the geometry
+	// on Z (geometry.scale(1,1,-1)) and that mirrored vertex IS the on-screen direction; the skybox and
+	// environment lighting are likewise sampled in true world directions. So we must NOT undo the mirror
+	// here - doing so reflects the sampling azimuth and flips the panorama left-right vs. the skybox.
+	// backgroundRotation is applied to the sampling direction (exactly like the skybox does in
+	// backgroundCube.glsl), NOT by rotating the mesh - that keeps the floor flat and matches the skybox at
+	// the horizon for any background rotation.
+	vNeedleGroundProjectionWorldDirection = needleGroundProjectionBackgroundRotation * transformDirection( position, modelMatrix );
 #endif`
             );
 
@@ -271,6 +290,25 @@ export class GroundProjectedEnv extends Behaviour {
     private _projection?: GroundProjection;
     private _watcher?: Watch;
 
+    /** The scene's real backgroundBlurriness, stored while we temporarily override it for the render. */
+    private _savedBackgroundBlur: number | null = null;
+
+    /** pre_render_callback: force the skybox blur just before the render (after all component onBeforeRender). */
+    private readonly _forceBackgroundBlur = (_frame?: XRFrame | null) => {
+        if (this._savedBackgroundBlur !== null) return; // already overriding (safety)
+        if (!(this.scene.background instanceof Texture)) return; // no skybox to blur
+        const current = this.scene.backgroundBlurriness ?? 0;
+        this._savedBackgroundBlur = current;
+        this.scene.backgroundBlurriness = 1;
+    };
+
+    /** post_render_callback: restore the scene's real blur right after the render. */
+    private readonly _restoreBackgroundBlur = () => {
+        if (this._savedBackgroundBlur === null) return;
+        this.scene.backgroundBlurriness = this._savedBackgroundBlur;
+        this._savedBackgroundBlur = null;
+    };
+
 
     /** @internal */
     awake() {
@@ -291,11 +329,23 @@ export class GroundProjectedEnv extends Behaviour {
                 this._needsTextureUpdate = true;
             });
         }
+        // Force the skybox blur via the render-bracketing callbacks (these run after every component's
+        // onBeforeRender, so the override can't be clobbered by e.g. Camera.applyClearFlags).
+        if (this.context.pre_render_callbacks.indexOf(this._forceBackgroundBlur) < 0)
+            this.context.pre_render_callbacks.push(this._forceBackgroundBlur);
+        if (this.context.post_render_callbacks.indexOf(this._restoreBackgroundBlur) < 0)
+            this.context.post_render_callbacks.push(this._restoreBackgroundBlur);
     }
     /** @internal */
     onDisable() {
         this._watcher?.revoke();
         this._projection?.removeFromParent();
+        const pre = this.context.pre_render_callbacks.indexOf(this._forceBackgroundBlur);
+        if (pre >= 0) this.context.pre_render_callbacks.splice(pre, 1);
+        const post = this.context.post_render_callbacks.indexOf(this._restoreBackgroundBlur);
+        if (post >= 0) this.context.post_render_callbacks.splice(post, 1);
+        // If we were disabled mid-frame (after force, before restore), put the real value back.
+        this._restoreBackgroundBlur();
     }
     /** @internal */
     onEnterXR(): void {
@@ -312,7 +362,21 @@ export class GroundProjectedEnv extends Behaviour {
     /** @internal */
     onBeforeRender(): void {
         if (this._projection && this.scene.backgroundRotation) {
-            this._projection.rotation.copy(this.scene.backgroundRotation);
+            // Mirror three's WebGLBackground: build the same mat3 it applies to the skybox sampling
+            // direction and feed it to our shader. This rotates the sampled environment exactly like the
+            // skybox (backgroundCube.glsl) instead of rotating the mesh - keeping the floor flat and the
+            // horizon aligned with the skybox for any background rotation.
+            _backgroundRotationEuler.copy(this.scene.backgroundRotation);
+            // accommodate left-handed frame (same as WebGLBackground.js)
+            _backgroundRotationEuler.x *= -1;
+            _backgroundRotationEuler.y *= -1;
+            _backgroundRotationEuler.z *= -1;
+            // Note: the extra cube-texture flip in WebGLBackground only applies to raw CubeTextures, not the
+            // PMREM render-target env this shader path samples - so it is intentionally omitted here.
+            const uniforms = getGroundProjectionShaderUniforms(this._projection.material);
+            uniforms.needleGroundProjectionBackgroundRotation.value.setFromMatrix4(
+                _backgroundRotationMatrix.makeRotationFromEuler(_backgroundRotationEuler)
+            );
         }
 
         if (this._projection && this.context.scene.background instanceof Texture) {

package/src/engine-components/NeedleMenu.ts

@@ -49,8 +49,8 @@ export class NeedleMenu extends Behaviour {
     @serializable()
     position: "top" | "bottom" = "bottom";
 
-    /** 
-     * Controls the visibility of the Needle logo in the menu (requires PRO license)
+    /**
+     * Controls the visibility of the Needle logo in the menu (requires a commercial license)
      */
     @serializable()
     showNeedleLogo: boolean = false;
@@ -102,7 +102,10 @@ export class NeedleMenu extends Behaviour {
             this.context.menu.showFullscreenOption(true);
         if (this.createMuteButton === true)
             this.context.menu.showAudioPlaybackOption(true);
-        if (this.showSpatialMenu === true)
+        // Apply the value in BOTH directions: the spatial menu is enabled by
+        // default, so unchecking the option must explicitly disable it. Only skip
+        // when the field is unset (undefined) to keep the engine default.
+        if (this.showSpatialMenu !== undefined)
             this.context.menu.showSpatialMenu(this.showSpatialMenu);
         if (this.createQRCodeButton === true) {
             if (!DeviceUtilities.isMobileDevice()) {

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

@@ -56,6 +56,14 @@ function applyRotationAttribute(attr: string, target: { set(x: number, y: number
 }
 
 function applyTexture(context: IContext, texture: Texture, isBackground: boolean, isEnvironment: boolean) {
+    // Textures load asynchronously. The context can be disposed/torn down while a
+    // load is in flight (element removed, context disposed, scene switched) — at
+    // which point context.scene is set to null on dispose. Bail instead of
+    // dereferencing it (the rest of this function also touches context.scene).
+    if (!context.scene) {
+        if (debug) console.warn("Skybox: skipping applyTexture — context was torn down before the texture finished loading");
+        return;
+    }
     if (!(texture instanceof CubeTexture || texture instanceof CompressedCubeTexture)
         && texture.mapping !== CubeUVReflectionMapping) {
         texture.mapping = EquirectangularRefractionMapping;

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"