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

package/src/engine-components/SceneSwitcher.ts

@@ -723,6 +723,7 @@ export class SceneSwitcher extends Behaviour {
                     // unless the user defines that he wants to use the scene name
                     if (this.useSceneName) {
                         if (scene instanceof Object3D) queryParameterValue = scene.name;
+                        else if (scene instanceof AssetReference && scene.asset?.name) queryParameterValue = scene.asset.name;
                         else if (scene.url) queryParameterValue = sceneUriToName(scene.url);
                     }
                     // save the loaded scene as an url parameter

package/src/engine-components/SeeThrough.ts

@@ -249,10 +249,10 @@ export class SeeThrough extends Behaviour {
             }
 
             const materials = renderer.sharedMaterials;// : this.rendererMaterials.get(renderer);
-            if (!materials) return;
+            if (!materials?.length) return;
 
             const block = MaterialPropertyBlock.get(renderer.gameObject);
-            const currentOpacity = (block.getOverride("opacity")?.value ?? materials[0].opacity ?? 1);
+            const currentOpacity = (block.getOverride("opacity")?.value ?? materials[0]?.opacity ?? 1);
 
             let newAlpha = Mathf.lerp(currentOpacity, targetAlpha, duration <= 0 ? 1 : this.context.time.deltaTime / duration);;
             if (newAlpha >= 0.99) newAlpha = 1;

package/src/engine-components/api.ts

@@ -34,8 +34,8 @@
  * @module Built-in Components
  */
 
-export * from "./codegen/components.js";
 export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.js";
+export * from "./codegen/components.js";
 export { Collider } from "./Collider.js"; // export abstract type
 export { Behaviour, Component, GameObject } from "./Component.js";
 

package/src/engine-components/postprocessing/Effects/BloomEffect.ts

@@ -1,4 +1,4 @@
-import { BloomEffect as _BloomEffect, EffectAttribute } from "postprocessing";
+import type { BloomEffect as _BloomEffect } from "postprocessing";
 import { MathUtils } from "three";
 
 import { MODULES } from "../../../engine/engine_modules.js";

package/src/engine-components/postprocessing/Effects/Sharpening.ts

@@ -1,4 +1,3 @@
-import { EffectAttribute } from "postprocessing";
 import { Uniform } from "three";
 
 import { MODULES } from "../../../engine/engine_modules.js";
@@ -138,7 +137,7 @@ function createSharpeningEffectType() {
                     ["radius", new Uniform(1)],
                     // ["threshold", new Uniform(0)],
                 ]),
-                attributes: EffectAttribute.CONVOLUTION
+                attributes: MODULES.POSTPROCESSING.MODULE.EffectAttribute.CONVOLUTION
             });
         }
     }

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

@@ -14,10 +14,6 @@ import { threeToneMappingToEffectMode } from "./Effects/Tonemapping.utils.js";
 import { PostProcessingEffect, PostProcessingEffectContext } from "./PostProcessingEffect.js";
 import { orderEffects, PostprocessingEffectData, PostProcessingEffectOrder } from "./utils.js";
 
-declare const NEEDLE_USE_POSTPROCESSING: boolean;
-globalThis["NEEDLE_USE_POSTPROCESSING"] = globalThis["NEEDLE_USE_POSTPROCESSING"] !== undefined ? globalThis["NEEDLE_USE_POSTPROCESSING"] : true;
-
-
 const debug = getParam("debugpost");
 
 const activeKey = Symbol("needle:postprocessing-handler");
@@ -58,13 +54,13 @@ export class PostProcessingHandler implements IPostProcessingHandler {
 
     apply(components: PostProcessingEffect[]): Promise<void> {
         if ("env" in import.meta && (import.meta as any /* webpack support */ ).env.VITE_NEEDLE_USE_POSTPROCESSING === "false") {
-            if (debug) console.warn("Postprocessing is disabled via vite env setting");
-            else console.debug("Postprocessing is disabled via vite env setting");
+            if (debug) console.warn("POSTPROCESSING is disabled via vite env setting");
+            else console.debug("POSTPROCESSING is disabled via vite env setting");
             return Promise.resolve();
         }
         if (!NEEDLE_USE_POSTPROCESSING) {
-            if (debug) console.warn("Postprocessing is disabled via global vite define setting");
-            else console.debug("Postprocessing is disabled via vite define");
+            if (debug || isDevEnvironment()) console.warn("POSTPROCESSING is disabled via global vite define setting");
+            else console.debug("POSTPROCESSING is disabled via vite define");
             return Promise.resolve();
         }
 

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

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

package/src/engine-components/ui/Canvas.ts

@@ -4,7 +4,7 @@ import * as ThreeMeshUI from 'three-mesh-ui'
 import { Mathf } from "../../engine/engine_math.js";
 import { serializable } from "../../engine/engine_serialization_decorator.js";
 import { FrameEvent } from "../../engine/engine_setup.js";
-import { delayForFrames, getParam } from "../../engine/engine_utils.js";
+import { getParam } from "../../engine/engine_utils.js";
 import { type NeedleXREventArgs } from "../../engine/xr/api.js";
 import { Camera } from "../Camera.js";
 import { GameObject } from "../Component.js";
@@ -236,19 +236,13 @@ export class Canvas extends UIRootComponent implements ICanvas {
         }
     }
 
-    async onEnterXR(args: NeedleXREventArgs) {
+    onEnterXR(args: NeedleXREventArgs) {
         // workaround for https://linear.app/needle/issue/NE-4114
         if (this.screenspace) {
             if (args.xr.isVR || args.xr.isPassThrough) {
                 this.gameObject.visible = false;
             }
         }
-        else {
-            this.gameObject.visible = false;
-            await delayForFrames(1).then(()=>{
-                this.gameObject.visible = true;
-            });
-        }
     }
     onLeaveXR(args: NeedleXREventArgs): void {
         if (this.screenspace) {

package/src/engine-components/ui/Text.ts

@@ -170,12 +170,15 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
             this._font = val;
             this.uiObject?.set(this.getTextOpts());
             this.markDirty();
+            // If the font is assigned during deserialization it means the font URL MUST be resolved with the style suffix. If it's assigned at runtime by a user invocation and is absolute then we assume the user is prividing a full path to the font asset json or png
+            this._assignedAtRuntime = this.__didAwake;
         }
     }
     get font(): string | null {
         return this._font;
     }
     private _font: string | null = "https://cdn.needle.tools/static/fonts/msdf/arial/arial";
+    private _assignedAtRuntime: boolean = true;
 
 
     /**
@@ -274,7 +277,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
     }
 
     protected onCreate(_opts: any): void {
-        if (debug) console.log(this);
+        if (debug) console.log("[Text] onCreate", this);
 
         // @marwie : Should be fixed. Currently _opts are always fed with :
         //          backgroundOpacity : color.opacity
@@ -442,7 +445,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
     private feedText(text: string, richText: boolean): void {
         // if (!text || text.length <= 0) return;
         // if (!text ) return;
-        if (debug) console.log("feedText", this.uiObject, text, richText);
+        if (debug) console.log("[Text] feedText", this.uiObject, text, richText);
 
         if (!this.uiObject) return;
         if (!this._textMeshUi)
@@ -603,16 +606,17 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
      * @private
      */
     private setFont(opts: ThreeMeshUIEveryOptions, fontStyle: FontStyle) {
-        
+
         if (!this.font) {
-            if(debug) console.warn("No font set for Text component, skipping font setup");
+            if (debug) console.warn("[Text] No font set for Text component, skipping font setup");
             return;
         }
 
         const fontName = this.font;
+
         const familyName = this.getFamilyNameWithCorrectSuffix(fontName, fontStyle);
 
-        if (debug) console.log("Selected font family:" + familyName, this.font);
+        if (debug) console.log(`[Text] Selected font family '${familyName}' from ${fontName} with style ${FontStyle[fontStyle]}`);
 
         // ensure a font family is register under this name
         let fontFamily = ThreeMeshUI.FontLibrary.getFontFamily(familyName as string);
@@ -676,7 +680,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
         // e.g. -Medium, -Black, -Thin...
         const styleName = familyName.substring(styleSeparator + 1)?.toLowerCase();
         if (unsupportedStyleNames.includes(styleName)) {
-            if (debug) console.warn("Unsupported font style: " + styleName);
+            if (debug) console.warn("[Text] Unsupported font style: " + styleName);
             return familyName;
         }
 
@@ -691,12 +695,12 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
         const isUpperCase = fontBaseName[0] === fontBaseName[0].toUpperCase();
         const fontNameWithoutSuffix = familyName.substring(0, styleSeparator > pathSeparatorIndex ? styleSeparator : familyName.length);
 
-        if (debug) console.log("Select font: ", familyName, FontStyle[style], fontBaseName, isUpperCase, fontNameWithoutSuffix);
+        if (debug) console.log("[Text] Select font: ", familyName, FontStyle[style], fontBaseName, isUpperCase, fontNameWithoutSuffix);
 
         /**
          * If a user provides a font with an absolute URL AND the font name does not end with "-msdf.json" or ".png" (e.g. "https://example.com/fonts/Arial-Bold"), we will assume that the user is providing the full path to the font files and we will not try to modify the font name based on the style. This allows users to have more control over the font files they are using, especially if they are hosting their own fonts or using a custom font provider that does not follow the same naming conventions as our default fonts.
          */
-        if (isAbsolute && !(familyName.endsWith("-msdf.json") || familyName.endsWith(".png"))) {
+        if (isAbsolute && this._assignedAtRuntime && !(familyName.endsWith("-msdf.json") || familyName.endsWith(".png"))) {
             return fontNameWithoutSuffix;
         }
 

package/src/engine-components/web/CursorFollow.ts

@@ -289,20 +289,28 @@ export class CursorFollow extends Behaviour {
 
 
         if (this.snapToSurface) {
-            ray.origin = _position;
-            ray.direction = rayDirection.multiplyScalar(-1);
-            const hits = this.context.physics.raycastFromRay(ray);
-            if (hits?.length) {
-                const hit = hits[0];
-                if (this.damping > 0) {
-                    this.gameObject.worldPosition = _position.lerp(hit.point, this.context.time.deltaTime / this.damping);
-                }
-                else {
-                    this.gameObject.worldPosition = hit.point;
+            ray.origin = cameraPosition;
+            ray.direction = rayDirection;
+            const hits = this.context.physics.raycastFromRay(ray, {
+                testObject: obj => {
+                    return obj !== this.gameObject && !this.gameObject.contains(obj) ? true : false
                 }
-
-                if(debug) {
-                    Gizmos.DrawLine(hit.point, hit.normal!.add(hit.point), 0x00FF00);
+            });
+            if (hits?.length) {
+                // Get the first hit that is not a child of *this* object. Because we do not want to lerp to a surface that is part of the object itself, since that would result in *this* object moving closer and closer to the camera as it tries to snap to itself
+                const hit = hits[0];//.find(h => !this.gameObject.contains(h.object));
+                if (hit) {
+                    if (this.damping > 0) {
+                        this.gameObject.worldPosition = _position.lerp(hit.point, this.context.time.deltaTime / this.damping);
+                        // this._distance = this.gameObject.worldPosition.distanceTo(cameraPosition);
+                    }
+                    else {
+                        this.gameObject.worldPosition = hit.point;
+                        // this._distance = hit.point.distanceTo(cameraPosition);
+                    }
+                    if (debug) {
+                        Gizmos.DrawLine(hit.point, hit.normal!.add(hit.point), 0x00FF00);
+                    }
                 }
             }
         }

package/src/engine-components/web/ScrollFollow.ts

@@ -1,5 +1,5 @@
-// For firefox ViewTimeline support
-import "scroll-timeline-polyfill/dist/scroll-timeline.js";
+// For firefox ViewTimeline support — dynamic import to avoid SSR crashes (polyfill accesses window at module level)
+if (typeof window !== "undefined") import("scroll-timeline-polyfill/dist/scroll-timeline.js");
 
 import { Box3, Object3D } from "three";
 

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

@@ -886,9 +886,11 @@ async function loadImage(url: string) {
     }
     const promise = new Promise<boolean>(res => {
         _imageElements.set(url, null);
+        if(isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Start loading image for tracking: ${url}`);
         const imageElement = document.createElement("img") as HTMLImageElement;
         imageElement.src = url;
         imageElement.addEventListener("load", async () => {
+            if(isDevEnvironment() || debug) console.debug(`[WebXRImageTracking] Loaded image for tracking: ${url}`);
             const img = await createImageBitmap(imageElement);
             _imageElements.set(url, img);
             res(true);

package/src/needle-engine.ts

@@ -1,3 +1,6 @@
+/// <reference path="../plugins/types/needle-bindings.d.ts" />
+/// <reference path="./engine/webcomponents/jsx.d.ts" />
+
 import { initEngine } from "./engine/engine_init.js";
 initEngine();
 import "./engine/webcomponents/needle-engine.js";

package/src/vite-env.d.ts

@@ -0,0 +1,16 @@
+// Vite global defines — see plugins/vite/defines.js
+// declare const entries here are picked up globally (ambient, no import/export).
+// Vite sets these as globals in dev and statically replaces them at build time.
+// Webpack DefinePlugin replaces them at build time too.
+// The globalThis fallbacks for vanilla JS are in engine_constants.ts.
+
+declare const NEEDLE_ENGINE_VERSION: string;
+declare const NEEDLE_ENGINE_GENERATOR: string;
+declare const NEEDLE_PROJECT_BUILD_TIME: string;
+declare const NEEDLE_PUBLIC_KEY: string;
+
+// #region treeshake flags
+// declare var (not const) so globalThis["NEEDLE_USE_*"] access is also type-safe
+declare var NEEDLE_USE_RAPIER: boolean;
+declare var NEEDLE_USE_POSTPROCESSING: boolean;
+// #endregion treeshake flags