@needle-tools/engine 4.10.5-next.a5d5bf4 → 4.11.0-beta.1

package/src/engine-components/SeeThrough.ts

@@ -0,0 +1,256 @@
+import { Material, Object3D, Vector3 } from "three";
+
+import { Gizmos } from "../engine/engine_gizmos.js";
+import { Mathf } from "../engine/engine_math.js";
+import { serializable } from "../engine/engine_serialization_decorator.js";
+import { getTempVector } from "../engine/engine_three_utils.js";
+import { getParam } from "../engine/engine_utils.js";
+import { Behaviour } from "./Component.js";
+import { Renderer } from "./Renderer.js";
+
+const debugSeeThrough = getParam("debugseethrough");
+
+type MaterialState = {
+    opacity: number,
+    transparent: boolean,
+    alphaHash: boolean
+}
+
+type MaterialWithState = Material & {
+    /** Original values */
+    userData: {
+        seeThrough: {
+            initial: MaterialState,
+        }
+    }
+};
+
+let i = 0;
+
+
+/**
+ * Makes the object fade out when it is obscuring the reference point from the camera. This component can be put on any object in the scene. It will affect all Renderer components on the same object and child objects. 
+ * 
+ * Useful for e.g. making walls transparent when the camera is outside or hiding object's that would otherwise block the view.  
+ * 
+ * Requires a Renderer component on the same object or a child object.
+ * 
+ * - Example https://see-through-walls-z23hmxbz1kjfjn.needle.run/
+ */
+export class SeeThrough extends Behaviour {
+
+    /**
+     * Assign a reference point - if this point will be obscured from the camera by this object then this object will fade out.  
+     * If no reference point is assigned the scene's root object will be used as reference point.
+     */
+    @serializable(Object3D)
+    referencePoint: Object3D | null = null;
+
+    /** 
+     * Fade Duration in seconds 
+     * @default 0.05
+    */
+    @serializable()
+    fadeDuration: number = .05;
+
+    /** 
+     * Minimum alpha value when fading out (0-1)
+     * @default 0
+     */
+    @serializable()
+    minAlpha: number = 0;
+
+    /**
+     * When useAlphaHash is enabled the object will fade out using alpha hashing, this means the object can stay opaque. If disabled the object will set to be transparent when fading out.
+     * @default true
+     */
+    @serializable()
+    useAlphaHash: boolean = true;
+
+    /**
+     * Set this to force updating the reference point position and direction
+     */
+    set needsUpdate(val: boolean) {
+        this._needsUpdate = val;
+    }
+    get needsUpdate() {
+        return this._needsUpdate;
+    }
+
+    /**
+     * Override the alpha value, -1 means no override
+     * @default -1
+     */
+    @serializable()
+    overrideAlpha: number = -1;
+
+    /**
+     * 
+     */
+    @serializable()
+    autoUpdate: boolean = true;
+
+
+    private readonly _referencePointVector: Vector3 = new Vector3();
+    private readonly _referencePointDir: Vector3 = new Vector3();
+    private _distance: number = 0;
+    private _renderer: Renderer[] | null = null;
+    private _needsUpdate = true;
+    private _id = i++;
+
+    /** * @internal */
+    onEnable() {
+        this._needsUpdate = true;
+        this._renderer = null;
+    }
+
+    /**  @internal */
+    onDisable() {
+        this._renderer?.forEach(r => {
+            const original = this.rendererMaterialsOriginal.get(r);
+            for (let i = 0; i < r.sharedMaterials.length; i++) {
+                const mat = r.sharedMaterials[i];
+                if (!mat) continue;
+                if (original && original[i]) {
+                    r.sharedMaterials[i] = original[i];
+                }
+            }
+            this.rendererMaterials.delete(r);
+            this.rendererMaterialsOriginal.delete(r);
+        });
+    }
+
+    /**
+     * @internal
+     */
+    update(): void {
+
+
+        if (this._needsUpdate) {
+            this._needsUpdate = false;
+            this._renderer = this.gameObject.getComponentsInChildren(Renderer);
+
+            // NOTE: instead of using the object's anchor (gameObject.worldPosition) we could also get the object's bounding box center:
+            // getBoundingBox(this.gameObject); // < import { getBoundingBox } from "@needle-tools/engine";
+            this.updateDirection();
+        }
+        else if (this.autoUpdate && (this.context.time.frame + this._id) % 20 === 0) {
+            this.updateDirection();
+        }
+
+
+
+        if (!this.autoUpdate) return;
+        if (!this.referencePoint) return;
+
+
+        const dot = this._referencePointDir.dot(this.context.mainCamera.worldForward);
+        const shouldHide = dot > .2;
+
+        if (debugSeeThrough && this.referencePoint) {
+            const wp = this.gameObject.worldPosition;
+            Gizmos.DrawArrow(getTempVector(wp), wp.sub(this._referencePointDir), shouldHide ? 0xFF0000 : 0x00FF00);
+            Gizmos.DrawWireSphere(this.referencePoint.worldPosition, .05, 0x0000FF);
+        }
+
+        if (shouldHide) {
+            this.updateAlpha(this.minAlpha, this.fadeDuration);
+        }
+        else {
+            this.updateAlpha(1, this.fadeDuration);
+        }
+    }
+
+    private readonly rendererMaterials = new WeakMap<Renderer, Array<MaterialWithState>>();
+    private readonly rendererMaterialsOriginal = new WeakMap<Renderer, Array<Material>>();
+
+    private updateDirection() {
+        this.referencePoint ??= this.context.scene;
+        this._referencePointVector.copy(this.gameObject.worldPosition.sub(this.referencePoint.worldPosition));
+        this._distance = this._referencePointVector.length();
+        this._referencePointDir.copy(this._referencePointVector)
+            .multiply(getTempVector(1, .5, 1)) // Reduce vertical influence
+            .normalize();
+    }
+
+
+    /**
+     * Update the alpha of the object's materials towards the target alpha over the given duration.
+     * @param targetAlpha Target alpha value (0-1)
+     * @param duration Duration in seconds to reach the target alpha. 0 means immediate. Default is the component's fadeDuration.
+     */
+    updateAlpha(targetAlpha: number, duration: number = this.fadeDuration) {
+
+        if (this.overrideAlpha !== undefined && this.overrideAlpha !== -1) {
+            targetAlpha = this.overrideAlpha;
+        }
+
+        this._renderer?.forEach(renderer => {
+
+            if (targetAlpha < .9) {
+                renderer.gameObject.raycastAllowed = false;
+            }
+            else {
+                renderer.gameObject.raycastAllowed = true;
+            }
+
+            if (!this.rendererMaterials.has(renderer)) {
+                const originalMaterials = new Array<Material>();
+                const clonedMaterials = new Array<MaterialWithState>();
+
+                // We clone the materials once and store them, so we can modify the opacity without affecting other objects using the same material. This could potentially be optimized further to re-use materials between renderers if multiple renderers use the same material.
+                for (let i = 0; i < renderer.sharedMaterials.length; i++) {
+                    const mat = renderer.sharedMaterials[i];
+                    if (!mat) continue;
+                    originalMaterials.push(mat);
+                    const matClone = mat.clone() as MaterialWithState;
+                    // @ts-ignore
+                    matClone.userData = mat.userData || {};
+                    matClone.userData.seeThrough = {
+                        initial: {
+                            opacity: matClone.opacity,
+                            transparent: matClone.transparent,
+                            alphaHash: matClone.alphaHash
+                        }
+                    }
+                    clonedMaterials.push(matClone);
+                    renderer.sharedMaterials[i] = matClone;
+                }
+
+                this.rendererMaterials.set(renderer, clonedMaterials);
+                this.rendererMaterialsOriginal.set(renderer, originalMaterials);
+            }
+
+            const materials = renderer.hasLightmap ? renderer.sharedMaterials : this.rendererMaterials.get(renderer);
+            if (!materials) return;
+
+            for (const mat of materials) {
+                if (!mat) continue;
+
+                let newAlpha = Mathf.lerp(mat.opacity, targetAlpha, duration <= 0 ? 1 : this.context.time.deltaTime / duration);;
+                if (newAlpha >= 0.99) newAlpha = 1;
+                else if (newAlpha <= 0.01) newAlpha = 0;
+
+
+                const wasTransparent = mat.transparent;
+                const wasAlphaHash = mat.alphaHash;
+
+                mat.alphaHash = this.useAlphaHash;
+
+                if (mat.userData && "seeThrough" in mat.userData) {
+                    const initial = mat.userData.seeThrough.initial as MaterialState;
+                    mat.opacity = initial.opacity * newAlpha;
+                    mat.transparent = mat.opacity >= 1 ? initial.transparent : !this.useAlphaHash;
+                }
+                else {
+                    mat.transparent = mat.opacity >= 1 ? false : !this.useAlphaHash;
+                }
+
+                if (wasTransparent != mat.transparent || wasAlphaHash != mat.alphaHash) {
+                    mat.needsUpdate = true;
+                }
+            }
+        });
+    }
+
+}

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

@@ -145,6 +145,7 @@ export { RendererLightmap } from "../RendererLightmap.js";
 export { Rigidbody } from "../RigidBody.js";
 export { SceneSwitcher } from "../SceneSwitcher.js";
 export { ScreenCapture } from "../ScreenCapture.js";
+export { SeeThrough } from "../SeeThrough.js";
 export { ShadowCatcher } from "../ShadowCatcher.js";
 export { RemoteSkybox } from "../Skybox.js";
 export { SmoothFollow } from "../SmoothFollow.js";

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

@@ -59,7 +59,19 @@ export class Graphic extends BaseUIComponent implements IGraphic, IRectTransform
             this.sRGBColor.copy(this._color);
             this.sRGBColor.convertLinearToSRGB();
             _colorStateObject.backgroundColor = this.sRGBColor;
-            _colorStateObject.backgroundOpacity = this._color.alpha * this._alphaFactor;
+            _colorStateObject.backgroundOpacity = this._color.alpha;
+
+            // E.g. when a button is setting states, we need to merge the state color with the base color
+            const activeStateName = this.uiObject["_simpleState__activeStates"]?.[0];
+            if (activeStateName) {
+                const active = this.uiObject["_simpleState__states"]?.[activeStateName];
+                if (active) {
+                    if ("backgroundColor" in active) _colorStateObject.backgroundColor = active["backgroundColor"];
+                    if ("backgroundOpacity" in active) _colorStateObject.backgroundOpacity = active["backgroundOpacity"];
+                }
+            }
+
+            _colorStateObject.backgroundOpacity *= this._alphaFactor;
             this.applyEffects(_colorStateObject, this._alphaFactor);
             this.uiObject.set(_colorStateObject);
             this.markDirty();

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

@@ -11,9 +11,8 @@ export class UIRaycastUtils {
     /** returns the real object when dealing with shadow UI */
     static getObject(obj: Object3D): Object3D {
         const shadowOwner = obj[$shadowDomOwner];
-        if(shadowOwner) 
-        {
-            if((shadowOwner as IComponent).isComponent === true) obj = (shadowOwner as IComponent).gameObject;
+        if (shadowOwner) {
+            if ((shadowOwner as IComponent).isComponent === true) obj = (shadowOwner as IComponent).gameObject;
             else obj = shadowOwner;
         }
         return obj;
@@ -29,8 +28,8 @@ export class UIRaycastUtils {
 
         obj = this.getObject(obj);
 
-        if(!obj.visible) return false;
-        
+        if (!obj.visible) return false;
+
         const canvasGroup = this.tryFindCanvasGroup(obj);
         if (canvasGroup?.isCanvasGroup === true) {
             if (out) out.canvasGroup = canvasGroup as ICanvasGroup;
@@ -38,7 +37,7 @@ export class UIRaycastUtils {
             if (canvasGroup.interactable === false) return false;
         }
         // handle Graphic Raycast target
-        const graphic : IGraphic | undefined = foreachComponent(obj, c => {
+        const graphic: IGraphic | undefined = foreachComponent(obj, c => {
             if ((c as unknown as IGraphic).isGraphic === true) return c;
             return undefined;
         }, false);
@@ -58,8 +57,10 @@ export class UIRaycastUtils {
         if (!obj) return null;
         // test for canvas groups
         const res = foreachComponent(obj, c => {
-            const gr = c as unknown as ICanvasGroup;
-            if (gr.blocksRaycasts !== undefined && gr.interactable !== undefined) return gr;
+            if (c.activeAndEnabled) {
+                const gr = c as unknown as ICanvasGroup;
+                if (gr.blocksRaycasts !== undefined && gr.interactable !== undefined) return gr;
+            }
             return undefined;
         }, false);
         if (res !== undefined) return res;

package/src/engine-components/utils/LookAt.ts

@@ -45,7 +45,10 @@ export class LookAt extends Behaviour implements UsdzBehaviour {
         let target: Object3D | null | undefined = this.target;
         if (!target) {
             target = this.context.mainCamera;
-            if (isDevEnvironment()) console.warn(`[LookAt] No target set on ${this.name}, using main camera as target.`);
+            if (isDevEnvironment() && !this["__did_warn"]) {
+                this["__did_warn"] = true;
+                console.debug(`[LookAt] No target set on ${this.name}, using main camera as target.`);
+            }
         }
         if (!target) return;
 

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

@@ -29,7 +29,8 @@ onStart(ctx => {
  * - Add the ClickThrough component to any GameObject in your scene.
  * - Alternatively, add the `clickthrough` attribute to the `<needle-engine>` HTML element (e.g. `<needle-engine clickthrough></needle-engine>`).
  * 
- * @link Example https://stackblitz.com/~/github.com/needle-engine/sample-3d-over-html
+ * - Example https://stackblitz.com/~/github.com/needle-engine/sample-3d-over-html
+ * 
  * @category Web
  * @group Components
  * @component

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

@@ -1,7 +1,14 @@
+import { Ray } from "three";
+
+import { Gizmos } from "../../engine/engine_gizmos.js";
 import { serializable } from "../../engine/engine_serialization_decorator.js";
 import { getTempVector } from "../../engine/engine_three_utils.js";
+import { getParam } from "../../engine/engine_utils.js";
 import { Behaviour } from "../Component.js";
 
+
+const debug = getParam("debugcursor");
+
 /**
  * The CursorFollow component makes the object follow the cursor (or touch) position on screen.  
  * 
@@ -34,9 +41,15 @@ export class CursorFollow extends Behaviour {
     @serializable()
     keepDistance: boolean = true;
 
-    
+    /**
+     * If true, the object will attempt to snap to the surface of other objects in the scene using a raycast.
+     */
+    @serializable()
+    snapToSurface: boolean = false;
+
+
     private _distance: number = -1;
-    updateDistance(force:boolean = false) {
+    updateDistance(force: boolean = false) {
         if (!force && (this.keepDistance && this._distance !== -1)) {
             return;
         }
@@ -48,10 +61,12 @@ export class CursorFollow extends Behaviour {
         this._distance = -1;
     }
 
+    /** @internal */
     onEnable(): void {
         this._distance = -1;
         window.addEventListener('pointermove', this._onPointerMove);
     }
+    /** @internal */
     onDisable(): void {
         window.removeEventListener('pointermove', this._onPointerMove);
     }
@@ -59,8 +74,8 @@ export class CursorFollow extends Behaviour {
     private _ndc_x = 0;
     private _ndc_y = 0;
 
-    private _onPointerMove = (e:PointerEvent) => {
-        if(!this.useFullPage) return;
+    private _onPointerMove = (e: PointerEvent) => {
+        if (!this.useFullPage) return;
         const x = e.clientX;
         const y = e.clientY;
         const domx = this.context.domX;
@@ -73,7 +88,7 @@ export class CursorFollow extends Behaviour {
 
 
     /** @internal */
-    update() {
+    lateUpdate() {
         // continuously update distance in case camera or object moves
         this.updateDistance();
 
@@ -89,16 +104,42 @@ export class CursorFollow extends Behaviour {
         rayDirection.sub(cameraPosition).normalize();
 
         // position object at initial distance along the ray
-        const newPosition = rayDirection.multiplyScalar(this._distance).add(cameraPosition);
+        const newPosition = getTempVector(rayDirection).multiplyScalar(this._distance).add(cameraPosition);
+        let _position = newPosition;
+
+
         if (this.damping > 0) {
             const pos = this.gameObject.worldPosition;
             pos.lerp(newPosition, this.context.time.deltaTime / this.damping);
             this.gameObject.worldPosition = pos;
+            _position = pos;
         }
         else {
             this.gameObject.worldPosition = newPosition;
         }
 
+
+        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;
+                }
+
+                if(debug) {
+                    Gizmos.DrawLine(hit.point, hit.normal!.add(hit.point), 0x00FF00);
+                }
+            }
+        }
+
     }
 
-}
+}
+
+const ray = new Ray();

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

@@ -473,7 +473,7 @@ function tryGetElementsForSelector(index: number): Element | null {
 
     if (!needsScrollMarkerRefresh) {
         const element = needleScrollMarkerCache[index] || null;
-        if (element) return element;
+        return element;
     }
     needsScrollMarkerRefresh = false;
     needleScrollMarkerCache.length = 0;