@needle-tools/engine 4.9.3 → 4.10.0-beta

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

@@ -0,0 +1,99 @@
+import { AnimationClip } from "three";
+
+import { ScaleClipType } from "../../engine/engine_animation.js";
+import { AnimationUtils } from "../../engine/engine_animation.js";
+import { serializable } from "../../engine/engine_serialization_decorator.js";
+import { registerType } from "../../engine/engine_typestore.js";
+import { Animation } from "../Animation.js";
+import { Behaviour } from "../Component.js";
+
+
+/**
+ * @category Web
+ * @group Components
+ * @component
+ */
+@registerType
+export class HoverAnimation extends Behaviour {
+
+    /**
+     * Default hover animation type if no custom clip is provided.  
+     * **Node**: This is only used if no custom hover animation clip is provided.  
+     * @default "linear"
+     */
+    @serializable()
+    type: ScaleClipType = "linear";
+
+    /**
+     * Duration of the hover animation in seconds.  
+     * **Node**: This is only used if no custom hover animation clip is provided.
+     * @default 0.1
+     */
+    @serializable()
+    duration: number = 0.1;
+
+    /**
+     * Scale factor to apply when hovering.  
+     * **Node**: This is only used if no custom hover animation clip is provided.
+     * @default 1.1
+     */
+    @serializable()
+    scaleFactor: number = 1.1;
+
+
+    /**
+     * Animation clip to play when hovering. If null, a default scale-up animation is used.
+     */
+    @serializable(AnimationClip)
+    hovered: AnimationClip | null = null;
+
+    /**
+     * Animation clip to play when not hovering. If null, an empty clip is used.
+     */
+    @serializable(AnimationClip)
+    idle: AnimationClip | null = null;
+
+    private animation: Animation | null = null;
+
+    start() {
+        if (!this.idle) this.idle = AnimationUtils.emptyClip();
+
+        if (!this.hovered) {
+            this.hovered = AnimationUtils.createScaleClip({
+                type: "linear",
+                duration: this.duration || 0.1,
+                scale: this.gameObject.scale,
+                scaleFactor: this.scaleFactor || 1.1,
+            });
+        }
+
+        this.animation ??= this.gameObject.addComponent(Animation);
+        this.animation.playAutomatically = false;
+        this.playIdle();
+    }
+
+    onEnable() {
+        if (this.animation) this.animation.enabled = true;
+        this.playIdle();
+    }
+    onDisable() {
+        if (this.animation) this.animation.enabled = false;
+        this.playIdle();
+    }
+
+    onPointerEnter() {
+        this.playHover();
+    }
+
+    onPointerExit() {
+        this.playIdle();
+    }
+
+    private playIdle() {
+        if (this.idle) this.animation?.play(this.idle, { exclusive: true, fadeDuration: .1, loop: true });
+    }
+    private playHover() {
+        if (this.hovered) this.animation?.play(this.hovered, { exclusive: true, fadeDuration: .1, loop: false, clampWhenFinished: true });
+    }
+
+}

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

@@ -1,8 +1,11 @@
 import { Box3, Object3D } from "three";
+import { element } from "three/src/nodes/TSL.js";
+import { Context } from "../../engine/engine_context.js";
 
 import { Mathf } from "../../engine/engine_math.js";
 import { serializable } from "../../engine/engine_serialization.js";
 import { getBoundingBox } from "../../engine/engine_three_utils.js";
+import { getParam } from "../../engine/engine_utils.js";
 import { Animation } from "../Animation.js";
 import { Animator } from "../Animator.js";
 import { AudioSource } from "../AudioSource.js";
@@ -11,6 +14,9 @@ import { EventList } from "../EventList.js";
 import { Light } from "../Light.js";
 import { SplineWalker } from "../splines/SplineWalker.js";
 import { PlayableDirector } from "../timeline/PlayableDirector.js";
+import { ScrollMarkerModel } from "../timeline/TimelineModels.js";
+
+const debug = getParam("debugscroll");
 
 type ScrollFollowEvent = {
     /** Event type */
@@ -44,6 +50,10 @@ type ScrollFollowEvent = {
  * 2. Add a ScrollFollow component to the same GameObject or another GameObject in the scene.
  * 3. Assign the PlayableDirector component to the ScrollFollow's target property.
  * 4. The timeline will now scrub based on the scroll position of the page.
+ * 
+ * @category Web
+ * @group Components
+ * @component
  */
 export class ScrollFollow extends Behaviour {
 
@@ -77,7 +87,8 @@ export class ScrollFollow extends Behaviour {
     @serializable()
     invert: boolean = false;
 
-    /**
+    /** 
+     * **Experimental - might change in future updates**  
      * If set, the scroll position will be read from the specified element instead of the window.  
      * Use a CSS selector to specify the element, e.g. `#my-scrollable-div` or `.scroll-container`.
      * @default null
@@ -98,17 +109,23 @@ export class ScrollFollow extends Behaviour {
      * Current scroll value in "pages" (0 = top of page, 1 = bottom of page)
      */
     get currentValue() {
-        return this.current_value;
+        return this._current_value;
     }
 
-    private current_value: number = 0;
-    private target_value: number = 0;
-    private applied_value: number = -1;
+    private _current_value: number = 0;
+    private _target_value: number = 0;
+    private _appliedValue: number = -1;
+
+
+    private _scrollStart: number = 0;
+    private _scrollEnd: number = 0;
+    private _scrollValue: number = 0;
+    private _scrollContainerHeight: number = 0;
 
     /** @internal */
     onEnable() {
         window.addEventListener("wheel", this.updateCurrentScrollValue, { passive: true });
-        this.applied_value = -1;
+        this._appliedValue = -1;
     }
 
     /** @internal */
@@ -121,23 +138,27 @@ export class ScrollFollow extends Behaviour {
 
         this.updateCurrentScrollValue();
 
-        // apply damping if any
-        if (this.damping > 0) {
-            this.current_value = Mathf.lerp(this.current_value, this.target_value, this.context.time.deltaTime / this.damping);
-        }
-        else {
-            this.current_value = this.target_value;
+        if (this._target_value >= 0) {
+            if (this.damping > 0) { // apply damping
+                this._current_value = Mathf.lerp(this._current_value, this._target_value, this.context.time.deltaTime / this.damping);
+                if (Math.abs(this._current_value - this._target_value) < 0.001) {
+                    this._current_value = this._target_value;
+                }
+            }
+            else {
+                this._current_value = this._target_value;
+            }
         }
 
-        if (this.current_value !== this.applied_value) {
-            this.applied_value = this.current_value;
+        if (this._current_value !== this._appliedValue) {
+            this._appliedValue = this._current_value;
 
             let defaultPrevented = false;
             if (this.changed.listenerCount > 0) {
                 // fire change event
                 const event: ScrollFollowEvent = {
                     type: "change",
-                    value: this.current_value,
+                    value: this._current_value,
                     component: this,
                     preventDefault: () => { event.defaultPrevented = true; },
                     defaultPrevented: false,
@@ -149,14 +170,21 @@ export class ScrollFollow extends Behaviour {
             // if not prevented apply scroll
             if (!defaultPrevented) {
 
-                const value = this.invert ? 1 - this.current_value : this.current_value;
+                const value = this.invert ? 1 - this._current_value : this._current_value;
+
+                const height = this._rangeEndValue - this._rangeStartValue;
+                const pixelValue = this._rangeStartValue + value * height;
 
                 // apply scroll to target(s)
                 if (Array.isArray(this.target)) {
-                    this.target.forEach(t => t && ScrollFollow.applyScroll(t, value));
+                    this.target.forEach(t => t && this.applyScroll(t, value));
                 }
                 else if (this.target) {
-                    ScrollFollow.applyScroll(this.target, value);
+                    this.applyScroll(this.target, value);
+                }
+
+                if (debug && this.context.time.frame % 30 === 0) {
+                    console.debug(`[ScrollFollow] ${this._current_value.toFixed(5)} — ${(this._target_value * 100).toFixed(0)}%`);
                 }
             }
         }
@@ -164,11 +192,16 @@ export class ScrollFollow extends Behaviour {
 
     private _lastSelectorValue: string | null = null;
     private _lastSelectorElement: Element | null = null;
+    /** Top y */
+    private _rangeStartValue: number = 0;
+    /** Bottom y */
+    private _rangeEndValue: number = 0;
 
     private updateCurrentScrollValue = () => {
 
         switch (this.mode) {
             case "window":
+
                 if (this.htmlSelector?.length) {
                     if (this.htmlSelector !== this._lastSelectorValue) {
                         this._lastSelectorElement = document.querySelector(this.htmlSelector);
@@ -176,27 +209,39 @@ export class ScrollFollow extends Behaviour {
                     }
                     if (this._lastSelectorElement) {
                         const rect = this._lastSelectorElement.getBoundingClientRect();
-                        this.target_value = -rect.top / (rect.height - window.innerHeight);
-                        if (isNaN(this.target_value) || !isFinite(this.target_value)) this.target_value = 0;
+
+                        this._scrollStart = rect.top + window.scrollY;
+                        this._scrollEnd = rect.height - window.innerHeight;
+                        this._scrollValue = -rect.top;
+                        this._target_value = -rect.top / (rect.height - window.innerHeight);
+                        this._rangeStartValue = rect.top + window.scrollY;
+                        this._rangeEndValue = this._rangeStartValue + rect.height - window.innerHeight;
+                        this._scrollContainerHeight = rect.height;
                         break;
                     }
                 }
                 else {
-                    this.target_value = window.scrollY / (document.body.scrollHeight - window.innerHeight);
+                    this._scrollStart = 0;
+                    this._scrollEnd = window.document.body.scrollHeight - window.innerHeight;
+                    this._scrollValue = window.scrollY;
+                    this._target_value = this._scrollValue / (this._scrollEnd || 1);
+                    this._rangeStartValue = 0;
+                    this._rangeEndValue = document.body.scrollHeight;
+                    this._scrollContainerHeight = window.innerHeight;
                 }
-                if (isNaN(this.target_value) || !isFinite(this.target_value)) this.target_value = 0;
                 break;
         }
 
+        if (isNaN(this._target_value) || !isFinite(this._target_value)) this._target_value = -1;
     }
 
 
-    private static applyScroll(target: object, value: number) {
+    private applyScroll(target: object, value: number) {
 
         if (!target) return;
 
         if (target instanceof PlayableDirector) {
-            target.time = value * target.duration;
+            this.handleTimelineTarget(target, value);
             if (!target.isPlaying) target.evaluate();
         }
         else if (target instanceof Animator) {
@@ -236,4 +281,116 @@ export class ScrollFollow extends Behaviour {
         }
     }
 
+
+
+    private handleTimelineTarget(director: PlayableDirector, value: number) {
+
+        const duration = director.duration;
+
+
+        let scrollRegionStart = Infinity;
+        let scrollRegionEnd = 0;
+        markersArray.length = 0;
+
+        for (const marker of director.foreachMarker<ScrollMarkerModel & { element?: HTMLElement | null, needsUpdate?: boolean }>("ScrollMarker")) {
+
+            // Get marker elements from DOM
+            if (marker.selector?.length && (marker.element === undefined || marker.needsUpdate === true || /** element is not in DOM anymore? */ (!marker.element?.parentNode))) {
+                marker.needsUpdate = false;
+                try {
+                    marker.element = document.querySelector<HTMLElement>(marker.selector) || null;
+                    if (debug) console.debug("ScrollMarker found on page", marker.element, marker.selector);
+                }
+                catch (error) {
+                    marker.element = null;
+                    console.error("ScrollMarker selector is not valid: " + marker.selector + "\n", error);
+                }
+            }
+
+            // skip markers without element (e.g. if the selector didn't return any element)
+            if (!marker.element) continue;
+
+            markersArray.push(marker);
+
+            const top = marker.element.offsetTop;
+            const height = marker.element.offsetHeight;
+            const bottom = top + height;
+            if (top < scrollRegionStart) {
+                scrollRegionStart = top;
+            }
+            if (bottom > scrollRegionEnd) {
+                scrollRegionEnd = bottom;
+            }
+        }
+
+
+
+        const currentTop = this._scrollValue;
+        const currentBottom = currentTop + this._scrollContainerHeight;
+
+        weightsArray.length = 0;
+        let sum = 0;
+
+        let markerCount = 0;
+        for (const marker of markersArray) {
+
+            if (!marker.element) continue;
+
+            const top = marker.element.offsetTop;
+            const height = marker.element.offsetHeight;
+            const bottom = top + height;
+            let overlap = 0;
+
+            // TODO: if we have two marker sections where no HTML overlaps (vor example because some large section is between them) we probably want to still virtually interpolate between them slowly in that region
+
+            if (bottom < currentTop) {
+                // marker is above scroll region
+                overlap = 0;
+            }
+            else if (top > currentBottom) {
+                // marker is below scroll region
+                overlap = 0;
+            }
+            else {
+                // calculate overlap in pixels
+                const overlapTop = Math.max(top, currentTop);
+                const overlapBottom = Math.min(bottom, currentBottom);
+                overlap = Math.max(0, overlapBottom - overlapTop);
+                // console.log(marker.element.className, overlap)
+            }
+
+            markerCount += 1;
+
+            if (overlap > 0) {
+                weightsArray.push({ time: marker.time, weight: overlap });
+                sum += overlap;
+            }
+        }
+
+        if (weightsArray.length <= 0 && markerCount <= 0) {
+            director.time = value * duration;
+        }
+        else if (weightsArray.length > 0) {
+            // normalize and calculate weighted time
+            let time = weightsArray[0].time;
+            for (const o of weightsArray) {
+                const weight = o.weight / Math.max(0.00001, sum);
+                // lerp time based on weight
+                const diff = Math.abs(o.time - time);
+                time += diff * weight;
+            }
+            director.time = time;
+        }
+    }
+
+}
+
+const weightsArray: OverlapInfo[] = [];
+const markersArray: (ScrollMarkerModel & { element?: HTMLElement | null })[] = [];
+
+type OverlapInfo = {
+    /** Marker time */
+    time: number,
+    /** Overlap in pixels */
+    weight: number,
 }

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

@@ -1,3 +1,4 @@
 export * from "./Clickthrough.js";
 export * from "./CursorFollow.js";
+export * from "./HoverAnimation.js";
 export * from "./ScrollFollow.js";