@needle-tools/engine 4.9.3 → 4.10.0-beta.1

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

@@ -1,12 +1,21 @@
 import { NEPointerEvent } from "../../engine/engine_input.js";
 import { onStart } from "../../engine/engine_lifecycle_api.js";
+import { addAttributeChangeCallback } from "../../engine/engine_utils.js";
 import { Behaviour } from "../Component.js";
 
 // Automatically add ClickThrough component if "clickthrough" attribute is present on the needle-engine element
 onStart(ctx => {
     const attribute = ctx.domElement.getAttribute("clickthrough");
-    if (attribute !== null && attribute !== "0" && attribute !== "false") {
-        ctx.scene.addComponent(ClickThrough);
+    if (clickthroughEnabled(attribute)) {
+        const comp = ctx.scene.addComponent(ClickThrough);
+        addAttributeChangeCallback(ctx.domElement, "clickthrough", () => {
+            const attribute = ctx.domElement.getAttribute("clickthrough");
+            comp.enabled = clickthroughEnabled(attribute);
+        });
+    }
+
+    function clickthroughEnabled(val: string | null) {
+        return val !== null && val !== "0" && val !== "false";
     }
 });
 
@@ -21,6 +30,9 @@ onStart(ctx => {
  * - 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
+ * @category Web
+ * @group Components
+ * @component
  */
 export class ClickThrough extends Behaviour {
 

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

@@ -4,6 +4,9 @@ import { Behaviour } from "../Component.js";
 
 /**
  * The CursorFollow component makes the object follow the cursor (or touch) position on screen.
+ * @category Web
+ * @group Components
+ * @component
  */
 export class CursorFollow extends Behaviour {
 

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,28 @@ 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 +171,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 +193,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,28 +210,41 @@ 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;
-            if (!target.isPlaying) target.evaluate();
+            this.handleTimelineTarget(target, value);
+            if (target.isPlaying) target.pause();
+            target.evaluate();
         }
         else if (target instanceof Animator) {
             target.setFloat("scroll", value);
@@ -236,4 +283,248 @@ export class ScrollFollow extends Behaviour {
         }
     }
 
+
+
+    private handleTimelineTarget(director: PlayableDirector, value: number) {
+
+        const duration = director.duration;
+
+
+        let scrollRegionStart = Infinity;
+        let scrollRegionEnd = 0;
+        markersArray.length = 0;
+
+        // querySelectorResults.length = 0;
+        let markerIndex = 0;
+
+        // https://scroll-driven-animations.style/tools/view-timeline/ranges
+        for (const marker of director.foreachMarker<ScrollMarkerModel & { element?: HTMLElement | null, needsUpdate?: boolean, timeline?: ViewTimeline }>("ScrollMarker")) {
+
+            const index = markerIndex++;
+
+            // Get marker elements from DOM
+            if ((marker.element === undefined || marker.needsUpdate === true || /** element is not in DOM anymore? */ (!marker.element?.parentNode))) {
+                marker.needsUpdate = false;
+                try {
+                    marker.element = tryGetElementsForSelector(index, marker.name) as HTMLElement | null;
+                    if (debug) console.debug("ScrollMarker found on page", marker.element, marker.name);
+                    // if (!marker.element) {
+                    //     marker.timeline = undefined;
+                    //     continue;
+                    // }
+                    // else {
+                    //     /** @ts-ignore */
+                    //     marker.timeline = new ViewTimeline({
+                    //         subject: marker.element,
+                    //         axis: 'block', // https://drafts.csswg.org/scroll-animations/#scroll-notation
+                    //     });
+                    // }
+                }
+                catch (error) {
+                    marker.element = null;
+                    console.error("ScrollMarker selector is not valid: " + marker.name + "\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;
+
+        // We keep a separate count here in case there are some markers that could not be resolved so point to *invalid* elements - the timeline should fallback to 0-1 scroll behaviour then
+        let markerCount = 0;
+        for (const marker of markersArray) {
+
+            if (!marker.element) continue;
+
+            markerCount += 1;
+
+            // const timeline = marker.timeline;
+            // if (timeline) {
+            //     const time01 = calculateTimelinePositionNormalized(timeline);
+            //     if (time01 > 0 && time01 <= 1) {
+            //         const overlap = calculateTimelinePositionNormalized(timeline!);
+            //         const weight = overlap;
+            //         // console.log(marker.element.className, time01)
+            //         weightsArray.push({ time: marker.time, weight: weight });
+            //         sum += weight;
+            //     }
+            // }
+            // continue;
+            // if(this.context.time.frame % 10 === 0) console.log(marker.element?.className, timeline, calculateTimelinePositionNormalized(timeline!));
+
+            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);
+            }
+
+            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 = 0;
+            for (const entry of weightsArray) {
+                const weight = entry.weight / Math.max(0.00001, sum);
+                // console.log(weight.toFixed(2))
+                // lerp time based on weight
+                const diff = Math.abs(entry.time - time);
+                time += diff * weight;
+            }
+            // console.log(time.toFixed(2), [...weightsArray])
+            if (this.damping <= 0)
+                director.time = time;
+            else
+                director.time = Mathf.lerp(director.time, time, this.context.time.deltaTime / this.damping);
+        }
+    }
+
+}
+
+
+
+const weightsArray: OverlapInfo[] = [];
+const markersArray: (ScrollMarkerModel & { element?: HTMLElement | null, timeline?: ViewTimeline })[] = [];
+
+type OverlapInfo = {
+    /** Marker time */
+    time: number,
+    /** Overlap in pixels */
+    weight: number,
+}
+
+
+// type SelectorCache = {
+//     /** The selector used to query the *elements */
+//     selector: string,
+//     elements: Element[] | null,
+//     usedElementCount: number,
+// }
+// const querySelectorResults: Array<SelectorCache> = [];
+
+const needleScrollMarkerCacheKey = "data-timeline-marker";
+const needleScrollMarkerIndexCache = new Map<number, Element | null>();
+const needleScrollMarkerNameCache = new Map<string, Element | null>();
+let needsScrollMarkerRefresh = true;
+
+function tryGetElementsForSelector(index: number, name: string): Element | null {
+
+    if (!needsScrollMarkerRefresh) {
+        let element = name?.length ? needleScrollMarkerNameCache.get(name) : null;
+        if (element) return element;
+        element = needleScrollMarkerIndexCache.get(index) || null;
+        return element;
+    }
+    needsScrollMarkerRefresh = false;
+    needleScrollMarkerIndexCache.clear();
+    const markers = document.querySelectorAll(`[data-timeline-marker]`);
+    markers.forEach((m, i) => {
+        needleScrollMarkerIndexCache.set(i, m);
+        const name = m.getAttribute("data-timeline-marker");
+        if (name?.length) needleScrollMarkerNameCache.set(name, m);
+    });
+    const element = needleScrollMarkerIndexCache.get(index) || null;
+    return element;
+
+
+    /* e.g. 
+    <div class="section behind start" data-needle-scroll-marker>
+    */
+    // console.log(index, element)
+    if (element) return element;
+
+    // for (const entry of querySelectorResults) {
+    //     if (entry.selector === selector) {
+    //         const index = entry.usedElementCount++;
+    //         return entry.elements && index < entry.elements.length ? entry.elements[index] : null;
+    //     }
+    // }
+    // const elements = document.querySelectorAll(selector);
+    // querySelectorResults.push({ selector, elements: Array.from(elements), usedElementCount: 1 });
+    // if (elements.length > 0) return elements[0];
+    return null;
+}
+
+
+// #region ScrollTimeline
+
+function calculateTimelinePositionNormalized(timeline: ViewTimeline) {
+    if (!timeline.source) return 0;
+    const currentTime = timeline.currentTime;
+    const duration = timeline.duration;
+    let durationValue = 1;
+    if (duration.unit === "seconds") {
+        durationValue = duration.value;
+    }
+    else if (duration.unit === "percent") {
+        durationValue = duration.value;
+    }
+    const t01 = currentTime.unit === "seconds" ? (currentTime.value / durationValue) : (currentTime.value / 100);
+    return t01;
+}
+function calculateNormalizedOverlap(timeline: ViewTimeline) {
+    if (!timeline.source) return 0;
+    const start = timeline.startOffset;
+    const end = timeline.endOffset;
+    const total = start.value + end.value;
+    if (total <= 0) return 1;
+    const startNorm = start.value / total;
+    const endNorm = end.value / total;
+    return 1 - (startNorm + endNorm);
+}
+
+
+declare global {
+    interface ViewTimeline {
+        axis: 'block' | 'inline';
+        currentTime: { unit: 'seconds' | 'percent', value: number };
+        duration: { unit: 'seconds' | 'percent', value: number };
+        source: Element | null;
+        startOffset: { unit: 'px', value: number };
+        endOffset: { unit: 'px', value: number };
+    }
 }