@needle-tools/engine 4.9.0-next.ce04b9f → 4.9.1

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

@@ -1,15 +1,64 @@
-import { Object3D } from "three";
-import { serializable } from "../../engine/engine_serialization.js";
+import { Box3, Object3D } from "three";
+
 import { Mathf } from "../../engine/engine_math.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 { Animation, PlayableDirector } from "../api.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 */
+    type: "change",
+    /** Current scroll value */
+    value: number,
+    /** ScrollFollow component that raised the event */
+    component: ScrollFollow,
+    /** Call to prevent invocation of default (e.g. updating targets) */
+    preventDefault: () => void,
+    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.
+ * 
+ * Assign {@link target} objects to the component to have them updated based on the current scroll position (check the 'target' property for supported types).
+ * 
+ * @link Example at https://scrollytelling-2-z23hmxby7c6x-u30ld.needle.run/
+ * @link Template at https://github.com/needle-engine/scrollytelling-template
+ * 
+ * ## How to use with an Animator
+ * 1. Create an Animator component and set up a float parameter named "scroll".
+ * 2. Create transitions between animation states based on the "scroll" parameter (e.g. from 0 to 1).
+ * 3. Add a ScrollFollow component to the same GameObject or another GameObject in the scene.
+ * 4. Assign the Animator component to the ScrollFollow's target property.
+ * 
+ * ## How to use with a PlayableDirector (timeline)
+ * 1. Create a PlayableDirector component and set up a timeline asset.
+ * 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.
+ */
 export class ScrollFollow extends Behaviour {
 
     /**
-     * Target object(s) to follow the scroll position of the page. If null, the main camera is used.
+     * Target object(s) to follow the scroll position of the page.
+     * 
+     * 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
+     * - SplineWalker, the scroll position will be mapped to the position01 property
+     * - Light, the scroll position will be mapped to the intensity property
+     * - Object3D, the object will move vertically based on the scroll position
+     * - Any object with a `scroll` property (number or function)
      */
     @serializable([Behaviour, Object3D])
     target: object[] | object | null = null;
@@ -21,8 +70,29 @@ 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()
-    mode: "window" = "window";
+    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()
+    private mode: "window" = "window";
+
+    /**
+     * Event fired when the scroll position changes
+     */
+    @serializable(EventList)
+    changed: EventList<ScrollFollowEvent> = new EventList<ScrollFollowEvent>();
 
     /**
      * Current scroll value in "pages" (0 = top of page, 1 = bottom of page)
@@ -33,58 +103,136 @@ export class ScrollFollow extends Behaviour {
 
     private current_value: number = 0;
     private target_value: number = 0;
+    private applied_value: number = -1;
 
     /** @internal */
     onEnable() {
-        window.addEventListener("wheel", this.updateCurrentScroll, { passive: true });
+        window.addEventListener("wheel", this.updateCurrentScrollValue, { passive: true });
+        this.applied_value = -1;
     }
 
     /** @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);
         }
-
-        // apply scroll to target(s)
-        if (Array.isArray(this.target)) {
-            this.target.forEach(t => t && this.applyScroll(t));
-        }
-        else if (this.target) {
-            this.applyScroll(this.target);
+        else {
+            this.current_value = this.target_value;
         }
 
+        if (this.current_value !== this.applied_value) {
+            this.applied_value = this.current_value;
+
+            let defaultPrevented = false;
+            if (this.changed.listenerCount > 0) {
+                // fire change event
+                const event: ScrollFollowEvent = {
+                    type: "change",
+                    value: this.current_value,
+                    component: this,
+                    preventDefault: () => { event.defaultPrevented = true; },
+                    defaultPrevented: false,
+                };
+                this.changed.invoke(event);
+                defaultPrevented = event.defaultPrevented;
+            }
+
+            // 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 && ScrollFollow.applyScroll(t, value));
+                }
+                else if (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 = 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) {
+                // TODO: remap position to use upper screen edge and lower edge instead of center
+                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 = value;
+            }
+            else if (typeof target.scroll === "function") {
+                target.scroll(value);
+            }
         }
     }