@needle-tools/engine 4.9.0-next.43185 → 4.9.0

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

@@ -1,11 +1,16 @@
-import { Object3D } from "three";
-import { serializable } from "../../engine/engine_serialization.js";
+import { Box3, Object3D } from "three";
+
 import { Mathf } from "../../engine/engine_math.js";
-import { Behaviour } from "../Component.js";
-import { PlayableDirector } from "../timeline/PlayableDirector.js";
-import { EventList } from "../EventList.js";
+import { serializable } from "../../engine/engine_serialization.js";
+import { getBoundingBox } from "../../engine/engine_three_utils.js";
 import { Animation } from "../Animation.js";
+import { Animator } from "../Animator.js";
 import { AudioSource } from "../AudioSource.js";
+import { Behaviour } from "../Component.js";
+import { EventList } from "../EventList.js";
+import { Light } from "../Light.js";
+import { SplineWalker } from "../splines/SplineWalker.js";
+import { PlayableDirector } from "../timeline/PlayableDirector.js";
 
 type ScrollFollowEvent = {
     /** Event type */
@@ -19,10 +24,23 @@ type ScrollFollowEvent = {
     defaultPrevented: boolean,
 }
 
+/**
+ * The ScrollFollow component allows you to link the scroll position of the page (or a specific element) to one or more target objects.  
+ * This can be used to create scroll-based animations, audio playback, or other effects. For example you can link the scroll position to a timeline (PlayableDirector) to create scroll-based storytelling effects or to an Animator component to change the animation state based on scroll.
+ * 
+ * @link Example at https://scrollytelling-2-z23hmxby7c6x-u30ld.needle.run/
+ */
 export class ScrollFollow extends Behaviour {
 
     /**
      * Target object(s) to follow the scroll position of the page. If null, the main camera is used.
+     * 
+     * Supported target types:
+     * - PlayableDirector (timeline), the scroll position will be mapped to the timeline time
+     * - Animator, the scroll position will be set to a float parameter named "scroll"
+     * - Animation, the scroll position will be mapped to the animation time
+     * - AudioSource, the scroll position will be mapped to the audio time
+     * - Any object with a `scroll` property (number or function)
      */
     @serializable([Behaviour, Object3D])
     target: object[] | object | null = null;
@@ -34,8 +52,23 @@ export class ScrollFollow extends Behaviour {
     @serializable()
     damping: number = 0;
 
+    /**
+     * If true, the scroll value will be inverted (e.g. scrolling down will result in a value of 0)
+     * @default false
+     */
+    @serializable()
+    invert: boolean = false;
+
+    /**
+     * 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
+     */
+    @serializable()
+    htmlSelector: string | null = null;
+
     @serializable()
-    mode: "window" = "window";
+    private mode: "window" = "window";
 
     /**
      * Event fired when the scroll position changes
@@ -56,23 +89,27 @@ export class ScrollFollow extends Behaviour {
 
     /** @internal */
     onEnable() {
-        window.addEventListener("wheel", this.updateCurrentScroll, { passive: true });
+        window.addEventListener("wheel", this.updateCurrentScrollValue, { passive: true });
         this.applied_value = -1;
-        this.updateCurrentScroll();
     }
 
     /** @internal */
     onDisable() {
-        window.removeEventListener("wheel", this.updateCurrentScroll);
+        window.removeEventListener("wheel", this.updateCurrentScrollValue);
     }
 
     /** @internal */
     lateUpdate() {
 
+        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.current_value !== this.applied_value) {
             this.applied_value = this.current_value;
@@ -94,55 +131,88 @@ export class ScrollFollow extends Behaviour {
             // if not prevented apply scroll
             if (!defaultPrevented) {
 
+                const value = this.invert ? 1 - this.current_value : this.current_value;
+
                 // apply scroll to target(s)
                 if (Array.isArray(this.target)) {
-                    this.target.forEach(t => t && this.applyScroll(t));
+                    this.target.forEach(t => t && ScrollFollow.applyScroll(t, value));
                 }
                 else if (this.target) {
-                    this.applyScroll(this.target);
+                    ScrollFollow.applyScroll(this.target, value);
                 }
             }
         }
     }
 
+    private _lastSelectorValue: string | null = null;
+    private _lastSelectorElement: Element | null = null;
 
-    private updateCurrentScroll = () => {
+    private updateCurrentScrollValue = () => {
 
         switch (this.mode) {
             case "window":
-                this.target_value = window.scrollY / (document.body.scrollHeight - window.innerHeight);
+                if (this.htmlSelector?.length) {
+                    if (this.htmlSelector !== this._lastSelectorValue) {
+                        this._lastSelectorElement = document.querySelector(this.htmlSelector);
+                        this._lastSelectorValue = this.htmlSelector;
+                    }
+                    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;
+                        break;
+                    }
+                }
+                else {
+                    this.target_value = window.scrollY / (document.body.scrollHeight - window.innerHeight);
+                }
                 if (isNaN(this.target_value) || !isFinite(this.target_value)) this.target_value = 0;
                 break;
         }
 
-        if (this.damping <= 0) {
-            this.current_value = this.target_value;
-        }
-
     }
 
 
-    private applyScroll(target: object) {
+    private static applyScroll(target: object, value: number) {
 
         if (!target) return;
 
         if (target instanceof PlayableDirector) {
-            target.time = this.current_value * target.duration;
+            target.time = value * target.duration;
             if (!target.isPlaying) target.evaluate();
         }
+        else if (target instanceof Animator) {
+            target.setFloat("scroll", value);
+        }
         else if (target instanceof Animation) {
-            target.time = this.current_value * target.duration;
+            target.time = value * target.duration;
         }
         else if (target instanceof AudioSource) {
             if (!target.duration) return;
-            target.time = this.current_value * target.duration;
+            target.time = value * target.duration;
+        }
+        else if (target instanceof SplineWalker) {
+            target.position01 = value;
+        }
+        else if (target instanceof Light) {
+            target.intensity = value;
+        }
+        else if (target instanceof Object3D) {
+            // When objects are assigned they're expected to move vertically based on scroll
+            if (target["needle:scrollbounds"] === undefined) {
+                target["needle:scrollbounds"] = getBoundingBox(target) || null;
+            }
+            const bounds = target["needle:scrollbounds"] as Box3;
+            if (bounds) {
+                target.position.y = -bounds.min.y - value * (bounds.max.y - bounds.min.y);
+            }
         }
         else if ("scroll" in target) {
             if (typeof target.scroll === "number") {
-                target.scroll = this.current_value;
+                target.scroll = value;
             }
             else if (typeof target.scroll === "function") {
-                target.scroll(this.current_value);
+                target.scroll(value);
             }
         }
     }