@needle-tools/engine 5.1.0-beta.1 → 5.1.0-beta.3

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/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/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 { $KhjWEFh } from "../../../engine/engine_license.js";
+import { _$gQv } 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 (!$KhjWEFh()) {
+        if (!_$gQv()) {
             if (name !== "") name += "-";
             name += "MadeWithNeedle";
         }
@@ -682,7 +682,7 @@ export class USDZExporter extends Behaviour {
                     if (debug)
                         showBalloonMessage("Quicklook url: " + callToActionURL);
                     if (callToActionURL) {
-                        if (!$KhjWEFh()) {
+                        if (!_$gQv()) {
                             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 (!$KhjWEFh()) {
+        if (!_$gQv()) {
             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/export/usdz/extensions/behavior/BehaviourComponents.ts

@@ -11,6 +11,7 @@ import { Animation } from "../../../../Animation.js";
 import { Animator } from "../../../../Animator.js";
 import { AudioSource } from "../../../../AudioSource.js";
 import { Behaviour, GameObject } from "../../../../Component.js";
+import type { ComponentInit } from "../../../../../engine/engine_types.js";
 import { Rigidbody } from "../../../../RigidBody.js";
 import type { IPointerClickHandler, PointerEventData } from "../../../../ui/PointerEvents.js";
 import { makeNameSafeForUSD, USDDocument, USDObject, USDZExporterContext } from "../../ThreeUSDZExporter.js";
@@ -811,13 +812,16 @@ export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler,
 
     ensureAudioSource() {
         if (!this.target) {
-            const newAudioSource = this.gameObject.addComponent(AudioSource);
+            const initializeAudioSource: ComponentInit<AudioSource> = {
+                spatialBlend: 1,
+                volume: 1,
+                loop: false,
+                clip: this.clip,
+                preload: true,
+            };
+            const newAudioSource = this.gameObject.addComponent(AudioSource, initializeAudioSource);
             if (newAudioSource) {
                 this.target = newAudioSource;
-                newAudioSource.spatialBlend = 1;
-                newAudioSource.volume = 1;
-                newAudioSource.loop = false;
-                newAudioSource.preload = true;
             }
         }
     }
@@ -828,6 +832,9 @@ export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler,
             label: "Play audio: " + (this.clip || this.target?.clip || "unknown clip"),
             hidden: false,
         })
+
+        this.ensureAudioSource();
+
     }
     onDisable(): void {
         this.context.accessibility.updateElement(this, {

package/src/engine-components/particlesystem/ParticleSystem.ts

@@ -593,6 +593,10 @@ class ColorBehaviour extends ParticleSystemBaseBehaviour {
         col.copy(this.system.main.startColor.evaluate(Math.random()));
         if (materialColor?.color) {
             tempColor.copy(materialColor.color);
+            // THREE.Color has no alpha — the material's color alpha is stored in
+            // material.opacity. Without this, a particle material's alpha/opacity
+            // was ignored (reported externally). multiply() propagates alpha.
+            tempColor.alpha = materialColor.opacity ?? 1;
             col.multiply(tempColor)
         }
         col.convertLinearToSRGB();

package/src/engine-components/webxr/WebXRImageTracking.ts

@@ -567,6 +567,7 @@ export class WebXRImageTracking extends Behaviour {
      * });
      * ```
      */
+    @serializable(EventList)
     imageTracked: EventList<WebXRImageTrackingEvent> = new EventList();
 
     /** @inheritdoc */