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

package/src/engine-components/physics/Attractor.ts

@@ -0,0 +1,35 @@
+import { Behaviour } from "../Component.js";
+import { Rigidbody } from "../RigidBody.js";
+import { serializable } from "../../engine/engine_serialization_decorator.js";
+
+
+
+export class Attractor extends Behaviour {
+
+    @serializable()
+    strength: number = 1;
+
+    @serializable()
+    radius: number = 2;
+
+    @serializable(Rigidbody)
+    targets: Rigidbody[] = [];
+
+
+    update() {
+        const wp = this.gameObject.worldPosition;
+        const factor = -this.strength * this.context.time.deltaTime;
+        this.targets.forEach(t => {
+            if(!t) return;
+            const dir = t.gameObject.worldPosition.sub(wp);
+            const length = dir.length();
+            if (length > this.radius) return;
+            let _factor = factor;
+            if (length > 1) _factor /= length * length;
+            else _factor /= Math.max(.05, length);
+            t.applyImpulse(dir.multiplyScalar(_factor));
+        })
+    }
+
+
+}

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

@@ -0,0 +1,64 @@
+import { NEPointerEvent } from "../../engine/engine_input.js";
+import { Behaviour } from "../Component.js";
+import { onStart } from "../../engine/engine_lifecycle_api.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);
+    }
+});
+
+
+/**
+ * ClickThrough component allows pointer events to "click through" the 3D canvas to HTML elements behind it.  
+ * 
+ * This is useful if you have a transparent canvas overlaying HTML content and want to interact with the HTML content through the transparent areas of the canvas.  
+ * 
+ * Usage Options:
+ * - Add the ClickThrough component to any GameObject in your scene.
+ * - 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
+ */
+export class ClickThrough extends Behaviour {
+
+    private _previousPointerEvents: string = 'all';
+
+    onEnable() {
+        // Register for pointer down and pointer move event
+        this.context.input.addEventListener('pointerdown', this.onPointerEvent);
+        this.context.input.addEventListener('pointermove', this.onPointerEvent, {
+            queue: 100,
+        });
+        window.addEventListener("touchend", this.onTouchEnd, { passive: true });
+        this._previousPointerEvents = this.context.domElement.style.pointerEvents;
+    }
+    onDisable() {
+        this.context.input.removeEventListener('pointerdown', this.onPointerEvent);
+        this.context.input.removeEventListener('pointermove', this.onPointerEvent);
+        window.removeEventListener("touchend", this.onTouchEnd);
+        this.context.domElement.style.pointerEvents = this._previousPointerEvents;
+    }
+    onPointerEnter() {
+        /** do nothing, necessary to raycast children */
+    }
+
+    private onPointerEvent = (evt: NEPointerEvent) => {
+        if (evt.pointerId > 0) return;
+        const intersections = evt.intersections;
+        // If we don't had any intersections during the 3D raycasting then we disable pointer events for the needle-engine element so that content BEHIND the 3D element can receive pointer events
+        if (intersections?.length <= 0) {
+            this.context.domElement.style.pointerEvents = 'none';
+        } else {
+            this.context.domElement.style.pointerEvents = 'all';
+        }
+    };
+
+    private onTouchEnd = (_evt: TouchEvent) => {
+        setTimeout(() => {
+            this.context.domElement.style.pointerEvents = 'all';
+        }, 100);
+    }
+}

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

@@ -0,0 +1,49 @@
+import { serializable } from "../../engine/engine_serialization_decorator.js";
+import { getTempVector } from "../../engine/engine_three_utils.js";
+import { Behaviour } from "../Component.js";
+
+
+export class CursorFollow extends Behaviour {
+
+    /**
+     * Damping for the movement, set to 0 for instant movement
+     * @default 0
+     */
+    @serializable()
+    damping: number = 0;
+
+
+    private _distance: number = -1;
+    updateDistance() {
+        this._distance = this.gameObject.worldPosition.distanceTo(this.context.mainCamera.worldPosition);
+    }
+
+
+    /** @internal */
+    update() {
+        // continuously update distance in case camera or object moves
+        this.updateDistance();
+
+        // follow cursor in screenspace but maintain initial distance from camera
+        const cursor = this.context.input.mousePositionRC;
+        const camera = this.context.mainCamera;
+        const cameraPosition = camera.worldPosition;
+
+        // create ray from camera through cursor position
+        const rayDirection = getTempVector(cursor.x, cursor.y, 1).unproject(camera);
+        rayDirection.sub(cameraPosition).normalize();
+
+        // position object at initial distance along the ray
+        const newPosition = rayDirection.multiplyScalar(this._distance).add(cameraPosition);
+        if (this.damping > 0) {
+            const pos = this.gameObject.worldPosition;
+            pos.lerp(newPosition, this.context.time.deltaTime / this.damping);
+            this.gameObject.worldPosition = pos;
+        }
+        else {
+            this.gameObject.worldPosition = newPosition;
+        }
+
+    }
+
+}

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";