@needle-tools/engine 4.9.0-alpha.4 → 4.9.0-beta

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

@@ -0,0 +1,173 @@
+import { Object3D } from "three";
+import { serializable } from "../../engine/engine_serialization.js";
+import { Mathf } from "../../engine/engine_math.js";
+import { Behaviour } from "../Component.js";
+import { PlayableDirector } from "../timeline/PlayableDirector.js";
+import { EventList } from "../EventList.js";
+import { Animation } from "../Animation.js";
+import { AudioSource } from "../AudioSource.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,
+}
+
+export class ScrollFollow extends Behaviour {
+
+    /**
+     * Target object(s) to follow the scroll position of the page. If null, the main camera is used.
+     */
+    @serializable([Behaviour, Object3D])
+    target: object[] | object | null = null;
+
+    /**
+     * Damping for the movement, set to 0 for instant movement
+     * @default 0
+     */
+    @serializable()
+    damping: number = 0;
+
+    /**
+     * 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`.
+     */
+    @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)
+     */
+    get currentValue() {
+        return this.current_value;
+    }
+
+    private current_value: number = 0;
+    private target_value: number = 0;
+    private applied_value: number = -1;
+
+    /** @internal */
+    onEnable() {
+        window.addEventListener("wheel", this.updateCurrentScrollValue, { passive: true });
+        this.applied_value = -1;
+    }
+
+    /** @internal */
+    onDisable() {
+        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;
+
+            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) {
+
+                // 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);
+                }
+            }
+        }
+    }
+
+    private _lastSelectorValue: string | null = null;
+    private _lastSelectorElement: Element | null = null;
+
+    private updateCurrentScrollValue = () => {
+
+        switch (this.mode) {
+            case "window":
+                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;
+        }
+
+    }
+
+
+    private applyScroll(target: object) {
+
+        if (!target) return;
+
+        if (target instanceof PlayableDirector) {
+            target.time = this.current_value * target.duration;
+            if (!target.isPlaying) target.evaluate();
+        }
+        else if (target instanceof Animation) {
+            target.time = this.current_value * target.duration;
+        }
+        else if (target instanceof AudioSource) {
+            if (!target.duration) return;
+            target.time = this.current_value * target.duration;
+        }
+        else if ("scroll" in target) {
+            if (typeof target.scroll === "number") {
+                target.scroll = this.current_value;
+            }
+            else if (typeof target.scroll === "function") {
+                target.scroll(this.current_value);
+            }
+        }
+    }
+
+}

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

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