@needle-tools/engine 4.10.0-next.f5ce0ae → 4.10.1-next.ffb3f90

package/src/engine-components/Camera.ts

@@ -36,7 +36,7 @@ const debugscreenpointtoray = getParam("debugscreenpointtoray");
  * Supports both perspective and orthographic cameras with various rendering options.
  * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
  * 
- * @category Camera Controls
+ * @category Camera
  * @group Components
  */
 export class Camera extends Behaviour implements ICamera {

package/src/engine-components/CharacterController.ts

@@ -14,7 +14,7 @@ import { Rigidbody } from "./RigidBody.js";
 const debug = getParam("debugcharactercontroller");
 
 /**
- * @category Camera Controls
+ * @category Camera
  * @group Components
  */
 export class CharacterController extends Behaviour {
@@ -107,7 +107,7 @@ export class CharacterController extends Behaviour {
 }
 
 /**
- * @category Camera Controls
+ * @category Camera
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/OrbitControls.ts

@@ -63,7 +63,7 @@ declare module 'three/examples/jsm/controls/OrbitControls.js' {
 /** The OrbitControls component is used to control a camera using the [OrbitControls from three.js](https://threejs.org/docs/#examples/en/controls/OrbitControls) library.  
  * The three OrbitControls object can be accessed via the `controls` property.  
  * The object being controlled by the OrbitControls (usually the camera) can be accessed via the `controllerObject` property.
- * @category Camera Controls
+ * @category Camera
  * @group Components
  */
 export class OrbitControls extends Behaviour implements ICameraController {

package/src/engine-components/SceneSwitcher.ts

@@ -80,7 +80,7 @@ export interface ISceneEventListener {
  * Available scenes are defined in the `scenes` array.   
  * Loaded scenes will be added to the SceneSwitcher's GameObject as a child and removed when another scene is loaded by the same SceneSwitcher.   
  * Live Examples
- * - [Multi Scenes Sample](https://engine.needle.tools/samples/multi-scenes-dynamic-loading) (source code available)
+ * - [Multi Scenes Sample](https://engine.needle.tools/samples/multi-scene-example) (source code available)
  * - [Needle Website](https://needle.tools)
  * - [Songs Of Cultures](https://app.songsofcultures.com)
  * 

package/src/engine-components/timeline/TimelineModels.ts

@@ -1,11 +1,16 @@
 import { AnimationClip, Object3D, Quaternion, Vector3 } from "three";
-import { Behavior } from "three-mesh-ui";
 
+/**
+ * @category Animation and Sequencing
+ */
 export declare type TimelineAssetModel = {
     name: string;
     tracks: TrackModel[];
 }
 
+/**
+ * @category Animation and Sequencing
+ */
 export enum TrackType {
     Activation = "ActivationTrack",
     Animation = "AnimationTrack",
@@ -15,6 +20,9 @@ export enum TrackType {
     Signal = "SignalTrack",
 }
 
+/**
+ * @category Animation and Sequencing
+ */
 export enum ClipExtrapolation {
     None = 0,
     Hold = 1,
@@ -23,6 +31,9 @@ export enum ClipExtrapolation {
     Continue = 4
 };
 
+/**
+ * @category Animation and Sequencing
+ */
 export declare type TrackModel = {
     name: string;
     type: TrackType;
@@ -37,11 +48,17 @@ export declare type TrackModel = {
 declare type Vec3 = { x: number, y: number, z: number };
 declare type Quat = { x: number, y: number, z: number, w: number };
 
+/**
+ * @category Animation and Sequencing
+ */
 export declare type TrackOffset = {
     position: Vec3 | Vector3;
     rotation: Quat | Quaternion;
 }
 
+/**
+ * @category Animation and Sequencing
+ */
 export declare type ClipModel = {
     start: number;
     end: number;
@@ -56,6 +73,9 @@ export declare type ClipModel = {
     reversed?: boolean;
 }
 
+/**
+ * @category Animation and Sequencing
+ */
 export declare type AnimationClipModel = {
     clip: string | number | AnimationClip;
     loop: boolean;
@@ -65,12 +85,18 @@ export declare type AnimationClipModel = {
     rotation?: Quat | Quaternion;
 }
 
+/**
+ * @category Animation and Sequencing
+ */
 export declare type AudioClipModel = {
     clip: string;
     loop: boolean;
     volume: number;
 }
 
+/**
+ * @category Animation and Sequencing
+ */
 export declare type ControlClipModel = {
     sourceObject: string | Object3D;
     controlActivation: boolean;
@@ -81,11 +107,16 @@ export enum MarkerType {
     Signal = "SignalEmitter",
 }
 
-export declare class MarkerModel {
+/**
+ * @category Animation and Sequencing
+ */export declare class MarkerModel {
     type: MarkerType;
     time: number;
 }
 
+/**
+ * @category Animation and Sequencing
+ */
 export declare class SignalMarkerModel extends MarkerModel {
     retroActive: boolean;
     emitOnce: boolean;
@@ -99,5 +130,8 @@ export declare class SignalMarkerModel extends MarkerModel {
  * ```html
  * <div data-timeline-marker>...</div>
  * ```
- */
+ * 
+ * @link [Example Project using ScrollMarker](https://scrollytelling-bike-z23hmxb2gnu5a.needle.run/)
+ * @category Animation and Sequencing
+*/
 export type ScrollMarkerModel = MarkerModel & { name: string };

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

@@ -40,6 +40,7 @@ type ScrollFollowEvent = {
  * 
  * @link Example at https://scrollytelling-2-z23hmxby7c6x-u30ld.needle.run/
  * @link Template at https://github.com/needle-engine/scrollytelling-template
+ * @link [Scrollytelling Bike Demo](https://scrollytelling-bike-z23hmxb2gnu5a.needle.run/)   
  * 
  * ## How to use with an Animator
  * 1. Create an Animator component and set up a float parameter named "scroll".

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

@@ -1,9 +1,11 @@
-import { Camera, PerspectiveCamera, Quaternion, Scene, Vector2, Vector3 } from "three";
+import { Camera, Matrix4, PerspectiveCamera, Quaternion, Scene, Vector2, Vector3 } from "three";
 
 import { isDevEnvironment } from "../../engine/debug/debug.js";
+import type { Context } from "../../engine/engine_context.js";
 import { Gizmos } from "../../engine/engine_gizmos.js";
+import { Mathf } from "../../engine/engine_math.js";
 import { serializable } from "../../engine/engine_serialization_decorator.js";
-import { getTempVector } from "../../engine/engine_three_utils.js";
+import { getTempQuaternion, getTempVector } from "../../engine/engine_three_utils.js";
 import { registerType } from "../../engine/engine_typestore.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { RGBAColor } from "../../engine/js-extensions/RGBAColor.js";
@@ -11,24 +13,57 @@ import { Behaviour } from "../Component.js";
 
 
 const debugParam = getParam("debugviewbox");
-const disabledGizmoColor = new RGBAColor(.5, .5, .5, .5);
+const disabledGizmoColor = new RGBAColor(.5, .5, .5, .3);
+const enabledGizmoColor = new RGBAColor(.5, .5, 0, 1);
 
 /**
  * This component can be used to automatically fit a certain box area into the camera view - no matter your screen size or aspect ratio.  
  * 
  * Add the ViewBox to an object into your scene
+ * 
+ * @link [Example on needle.run](https://viewbox-demo-z23hmxbz2gkayo-z1nyzm6.needle.run/)
+ * @link [Scrollytelling Demo using animated Viewbox](https://scrollytelling-bike-z23hmxb2gnu5a.needle.run/)   
+ * @link [Example on Stackblitz](https://stackblitz.com/edit/needle-engine-view-box-example)
+ * 
+ * @example Add a Viewbox component to an object in your scene
+ * ```ts
+  const viewBox = new Object3D();
+  viewBox.scale.set(0, 0, 0);
+  viewBox.addComponent(ViewBox, { debug: true });
+  scene.add(viewBox);
+ * ```
+  
+ * @category Camera
+ * @group Components
+ * @component
  */
 @registerType
 export class ViewBox extends Behaviour {
 
+    /** All known viewbox instances */
     static readonly instances: ViewBox[] = [];
 
+    /**
+     * The currently active viewbox (the last one that was set active). If you have multiple viewboxes in your scene, only the active one will be used.  
+     * Note that the last viewbox may be inactive if its component is disabled or disabled in the hierarchy.
+     * @returns The active viewbox or null if none is active
+     */
+    static get activeInstance(): ViewBox | null {
+        if (ViewBox.instances.length === 0) return null;
+        return ViewBox.instances[ViewBox.instances.length - 1];
+    }
+
+    /**
+     * A runner instance is used per context to update the viewbox
+     */
+    private static readonly runners: WeakMap<Context, Runner> = new WeakMap();
+
     /**
      * The reference field of view is used to calculate the box size. This should usually be the same as your camera's fov.
-     * @default undefined (meaning it will use the camera fov on the first frame)
+     * @default -1 (meaning it will use the camera fov on the first frame)
      */
     @serializable()
-    referenceFieldOfView: number | undefined = undefined;
+    referenceFieldOfView: number = -1;
 
     /**
      * Enable debug logs and rendering for this component instance
@@ -36,23 +71,47 @@ export class ViewBox extends Behaviour {
     @serializable()
     debug: boolean = false;
 
+
+    /**
+     * Set this ViewBox as the active one (if you have multiple in your scene). The last active one will be used.
+     * @returns self for chaining
+     */
+    setActive(): this {
+        this.enabled = true;
+        const idx = ViewBox.instances.indexOf(this);
+        if (idx !== -1) ViewBox.instances.splice(idx, 1);
+        ViewBox.instances.push(this);
+        return this;
+    }
+
+    /** @internal */
     onEnable(): void {
         if (debugParam || this.debug || isDevEnvironment()) console.debug("[ViewBox] Using camera fov:", this.referenceFieldOfView);
         // register instance
         ViewBox.instances.push(this);
+
+        this.removeUpdateCallback();
+        this.context.pre_render_callbacks.push(this.internalUpdate);
     }
 
+    /** @internal */
     onDisable(): void {
         if (debugParam || this.debug) console.debug("[ViewBox] Disabled");
         // unregister instance
         const idx = ViewBox.instances.indexOf(this);
         if (idx !== -1) ViewBox.instances.splice(idx, 1);
-        this._projectedBoxElement?.remove();
+        this.removeUpdateCallback();
+    }
+
+    private removeUpdateCallback() {
+        // remove prerender callback
+        const cbIdx = this.context.pre_render_callbacks.indexOf(this.internalUpdate);
+        if (cbIdx !== -1) this.context.pre_render_callbacks.splice(cbIdx, 1);
     }
 
-    onBeforeRender(): void {
+    private internalUpdate = () => {
         if (this.context.isInXR) return;
-        if (this.destroyed) return;
+        if (this.destroyed || !this.activeAndEnabled) return;
         const isActive = ViewBox.instances[ViewBox.instances.length - 1] === this;
         if (!isActive) {
             if (debugParam || this.debug) {
@@ -60,40 +119,85 @@ export class ViewBox extends Behaviour {
             }
             return;
         }
-        if (debugParam || this.debug) Gizmos.DrawWireBox(this.gameObject.worldPosition, this.gameObject.worldScale, 0xdddd00, 0, true, this.gameObject.worldQuaternion);
+        if (debugParam || this.debug) Gizmos.DrawWireBox(this.gameObject.worldPosition, this.gameObject.worldScale, enabledGizmoColor, 0, true, this.gameObject.worldQuaternion);
+
 
         // calculate box size to fit the camera frustrum size at the current position (just scale)
         const camera = this.context.mainCamera;
         if (!camera) return;
         if (!(camera instanceof PerspectiveCamera)) {
             // TODO: support orthographic camera
+            if (!this["__warnedOrthographic"]) {
+                console.warn("[ViewBox] Only perspective cameras are supported.");
+                this["__warnedOrthographic"] = true;
+            }
             return;
         }
 
-        if (this.referenceFieldOfView === undefined) {
+        if (this.referenceFieldOfView === undefined || this.referenceFieldOfView === -1) {
             this.referenceFieldOfView = camera.fov;
+            console.debug("[ViewBox] No referenceFieldOfView set, using camera fov:", this.referenceFieldOfView);
         }
-
         if (this.referenceFieldOfView === undefined || this.referenceFieldOfView <= 0) {
             if (debugParam || this.debug) console.warn("[ViewBox] No valid referenceFieldOfView set, cannot adjust box size:", this.referenceFieldOfView);
             return;
         }
 
-        const domWidth = this.context.domWidth;
-        const domHeight = this.context.domHeight;
+        let runner = ViewBox.runners.get(this.context);
+        if (!runner) {
+            runner = new Runner();
+            ViewBox.runners.set(this.context, runner);
+        }
+        runner.update(this);
+
+        // BACKLOG: some code for box scale of an object (different component)
+        // this.gameObject.worldScale = getTempVector(width, height, worldscale.z);
+        // this.gameObject.scale.multiplyScalar(.98)
+        // const minscale = Math.min(width, height);
+        // console.log(width, height);
+        // this.gameObject.worldScale = getTempVector(scale, scale, scale);
+    }
+
+}
+
+
+
+
+const projectionMatrixCopy: Matrix4 = new Matrix4();
+const projectionMatrixInverseCopy: Matrix4 = new Matrix4();
+
+class Runner {
+
+    private lastActiveViewBox: ViewBox | null = null;
+    private lastViewBoxChangeTime: number = -1;
+    private currentX: number = 0;
+    private currentY: number = 0;
+    private currentZoom: number = 1;
+
+    update(viewBox: ViewBox) {
+
+        const context = viewBox.context;
+        const camera = viewBox.context.mainCamera;
+        if (!(camera instanceof PerspectiveCamera)) return;
+
+        if (this.lastActiveViewBox !== viewBox) {
+            if (this.lastActiveViewBox === null)
+                this.lastViewBoxChangeTime = -100; // long ago
+            else
+                this.lastViewBoxChangeTime = context.time.time;
+            this.lastActiveViewBox = viewBox;
+        }
+
+        const domWidth = context.domWidth;
+        const domHeight = context.domHeight;
 
-        let rectPosX = 0;
-        let rectPosY = 0;
         let rectWidth = domWidth;
         let rectHeight = domHeight;
         let diffWidth = 1;
         let diffHeight = 1;
         // use focus rect if available
-        const focusRectSize = this.context.focusRectSize;
+        const focusRectSize = context.focusRectSize;
         if (focusRectSize) {
-            // console.log(focusRectSize)
-            rectPosX = focusRectSize.x;
-            rectPosY = focusRectSize.y;
             rectWidth = focusRectSize.width;
             rectHeight = focusRectSize.height;
             diffWidth = domWidth / rectWidth;
@@ -101,22 +205,28 @@ export class ViewBox extends Behaviour {
         }
 
 
+        // Copy the projection matrix and restore values so we can reset it later
+        projectionMatrixCopy.copy(camera.projectionMatrix);
+        projectionMatrixInverseCopy.copy(camera.projectionMatrixInverse);
         const view = camera.view;
         const zoom = camera.zoom;
         const aspect = camera.aspect;
         const fov = camera.fov;
+        // Set values to default so we can calculate the box size correctly
         camera.view = null;
         camera.zoom = 1;
-        camera.fov = this.referenceFieldOfView;
+        camera.fov = viewBox.referenceFieldOfView;
         camera.updateProjectionMatrix();
 
 
-        const boxPosition = this.gameObject.worldPosition;
-        const boxScale = this.gameObject.worldScale;
+        const boxPosition = viewBox.gameObject.worldPosition;
+        const boxScale = viewBox.gameObject.worldScale;
 
         const cameraPosition = camera.worldPosition;
         const distance = cameraPosition.distanceTo(boxPosition);
 
+        const timeSinceViewBoxChanged = context.time.time - this.lastViewBoxChangeTime;
+        const interpolationDelta = timeSinceViewBoxChanged < 1 ? (context.time.deltaTime / .1) : 1;
 
         // #region camera fixes
         // If the camera is inside the box, move it out
@@ -124,13 +234,13 @@ export class ViewBox extends Behaviour {
         const direction = getTempVector(cameraPosition).sub(boxPosition);
         if (distance < boxSizeMax) {
             // move camera out of bounds
-            if (this.debug || debugParam) console.warn("[ViewBox] Moving camera out of bounds", distance, "<", boxSizeMax);
+            if (viewBox.debug || debugParam) console.warn("[ViewBox] Moving camera out of bounds", distance, "<", boxSizeMax);
             const positionDirection = getTempVector(direction);
             positionDirection.y *= .00000001; // stay on horizontal plane mostly
             positionDirection.normalize();
-            const lengthToMove = (boxSizeMax - distance); 
+            const lengthToMove = (boxSizeMax - distance);
             const newPosition = cameraPosition.add(positionDirection.multiplyScalar(lengthToMove));
-            camera.worldPosition = newPosition.lerp(cameraPosition, 1 - this.context.time.deltaTime);
+            camera.worldPosition = newPosition.lerp(cameraPosition, 1 - context.time.deltaTime);
         }
 
         // Ensure the camera looks at the ViewBox
@@ -144,18 +254,26 @@ export class ViewBox extends Behaviour {
         //     camera.worldQuaternion = rotation;
         //     camera.updateMatrixWorld();
         // }
-        const boxPositionInCameraSpace = getTempVector(boxPosition);
-        camera.worldToLocal(boxPositionInCameraSpace);
-        camera.lookAt(boxPosition);
-        camera.updateMatrixWorld();
+        // const boxPositionInCameraSpace = getTempVector(boxPosition);
+
+        // Ensure the camera looks at the box position
+        // camera.worldToLocal(boxPositionInCameraSpace);
+        // if (interpolationDelta < 1) {
+        //     const startRotation = interpolationDelta < 1 ? getTempQuaternion(camera.quaternion) : null;
+        //     camera.lookAt(boxPosition);
+        //     if (startRotation !== null) {
+        //         camera.quaternion.slerpQuaternions(startRotation, camera.quaternion, interpolationDelta);
+        //     }
+        //     camera.updateMatrixWorld();
+        // }
 
 
         // #region calculate fit
-        const vFOV = this.referenceFieldOfView * Math.PI / 180; // convert vertical fov to radians
+        const vFOV = viewBox.referenceFieldOfView * Math.PI / 180; // convert vertical fov to radians
         const height = 2 * Math.tan(vFOV / 2) * distance; // visible height
         const width = height * camera.aspect; // visible width
 
-        const projectedBox = this.projectBoxIntoCamera(camera, 1);
+        const projectedBox = this.projectBoxIntoCamera(viewBox, camera, 1);
         // return
         const boxWidth = (projectedBox.maxX - projectedBox.minX);
         const boxHeight = (projectedBox.maxY - projectedBox.minY);
@@ -166,32 +284,38 @@ export class ViewBox extends Behaviour {
             width / diffWidth,
             height / diffHeight
         );
+        const rectZoom = scale / (height * .5);
         // console.log({ scale, width, height, boxWidth: boxWidth * camera.aspect, boxHeight, diffWidth, diffHeight, aspect: camera.aspect, distance })
         // this.context.focusRectSettings.zoom = 1.39;
         // if (!this.context.focusRect) this.context.setCameraFocusRect(this.context.domElement);
         // return
         const vec = getTempVector(boxPosition);
         vec.project(camera);
-        this.context.focusRectSettings.offsetX = vec.x;
-        this.context.focusRectSettings.offsetY = vec.y;
-        this.context.focusRectSettings.zoom = scale / (height * .5);
-        // if we don't have a focus rect yet, set it to the dom element
-        if (!this.context.focusRect) this.context.setCameraFocusRect(this.context.domElement);
+
+        if (interpolationDelta < 1) {
+            this.currentX = Mathf.lerp(this.currentX, vec.x, interpolationDelta);
+            this.currentY = Mathf.lerp(this.currentY, vec.y, interpolationDelta);
+            this.currentZoom = Mathf.lerp(this.currentZoom, rectZoom, interpolationDelta);
+        }
+        else {
+            this.currentX = vec.x;
+            this.currentY = vec.y;
+            this.currentZoom = rectZoom;
+        }
+
+        // Apply new values
+        context.focusRectSettings.offsetX = this.currentX;
+        context.focusRectSettings.offsetY = this.currentY;
+        context.focusRectSettings.zoom = this.currentZoom;
+        if (!context.focusRect) context.setCameraFocusRect(context.domElement); // if we don't have a focus rect yet, set it to the dom element
 
         // Reset values
         camera.view = view;
         camera.zoom = zoom;
         camera.aspect = aspect;
         camera.fov = fov;
-        // camera.updateProjectionMatrix();
-
-
-        // BACKLOG: some code for box scale of an object (different component)
-        // this.gameObject.worldScale = getTempVector(width, height, worldscale.z);
-        // this.gameObject.scale.multiplyScalar(.98)
-        // const minscale = Math.min(width, height);
-        // console.log(width, height);
-        // this.gameObject.worldScale = getTempVector(scale, scale, scale);
+        camera.projectionMatrix.copy(projectionMatrixCopy);
+        camera.projectionMatrixInverse.copy(projectionMatrixInverseCopy);
     }
 
 
@@ -206,7 +330,7 @@ export class ViewBox extends Behaviour {
 
 
 
-    private projectBoxIntoCamera(camera: Camera, _factor: number) {
+    private projectBoxIntoCamera(comp: ViewBox, camera: Camera, _factor: number) {
         const factor = .5 * _factor;
 
         const corners = [
@@ -225,7 +349,7 @@ export class ViewBox extends Behaviour {
         let maxY = Number.NEGATIVE_INFINITY;
         for (let i = 0; i < corners.length; i++) {
             const c = corners[i];
-            c.applyMatrix4(this.gameObject.matrixWorld);
+            c.applyMatrix4(comp.gameObject.matrixWorld);
             c.project(camera);
             if (c.x < minX) minX = c.x;
             if (c.x > maxX) maxX = c.x;
@@ -237,15 +361,15 @@ export class ViewBox extends Behaviour {
             if (!this._projectedBoxElement) {
                 this._projectedBoxElement = document.createElement("div");
             }
-            if (this._projectedBoxElement.parentElement !== this.context.domElement)
-                this.context.domElement.appendChild(this._projectedBoxElement);
+            if (this._projectedBoxElement.parentElement !== comp.context.domElement)
+                comp.context.domElement.appendChild(this._projectedBoxElement);
             this._projectedBoxElement.style.position = "fixed";
             // dotted but with larger gaps
             this._projectedBoxElement.style.outline = "2px dashed rgba(255,0,0,.5)";
-            this._projectedBoxElement.style.left = ((minX * .5 + .5) * this.context.domWidth) + "px";
-            this._projectedBoxElement.style.top = ((-maxY * .5 + .5) * this.context.domHeight) + "px";
-            this._projectedBoxElement.style.width = ((maxX - minX) * .5 * this.context.domWidth) + "px";
-            this._projectedBoxElement.style.height = ((maxY - minY) * .5 * this.context.domHeight) + "px";
+            this._projectedBoxElement.style.left = ((minX * .5 + .5) * comp.context.domWidth) + "px";
+            this._projectedBoxElement.style.top = ((-maxY * .5 + .5) * comp.context.domHeight) + "px";
+            this._projectedBoxElement.style.width = ((maxX - minX) * .5 * comp.context.domWidth) + "px";
+            this._projectedBoxElement.style.height = ((maxY - minY) * .5 * comp.context.domHeight) + "px";
             this._projectedBoxElement.style.pointerEvents = "none";
             this._projectedBoxElement.style.zIndex = "1000";
         }
@@ -258,5 +382,4 @@ export class ViewBox extends Behaviour {
 
 
 
-
-}
+}

package/src/engine-components/webxr/WebARSessionRoot.ts

@@ -465,6 +465,7 @@ export class WebARSessionRoot extends Behaviour {
             return;
         }
         else {
+            // @ts-ignore
             const anchor = await hit.createAnchor(session.viewerPose!.transform);
             // make sure the session is still active
             if (session.running && anchor) {