@needle-tools/engine 4.9.3-next.002c20b → 4.9.3-next.0facab6

package/src/engine-components/AnimatorController.ts

@@ -276,7 +276,7 @@ export class AnimatorController {
      * @returns The found state or null if not found
      */
     FindState(name: string | number | undefined | null): State | null { return this.findState(name); }
-    
+
     /**
      * Finds an animation state by name or hash.
      * 
@@ -321,6 +321,25 @@ export class AnimatorController {
         return action;
     }
 
+    // addState(state: State, layerIndex: number = 0) {
+    //     if (!this.model) throw new Error("AnimatorController model is missing");
+    //     if (layerIndex < 0 || layerIndex >= this.model.layers.length) {
+    //         throw new Error(`Invalid layer index: ${layerIndex}`);
+    //     }
+    //     const layer = this.model.layers[layerIndex];
+    //     if (!layer.stateMachine) {
+    //         layer.stateMachine = { states: [], defaultState: 0 };
+    //     }
+    //     if (!layer.stateMachine.states) {
+    //         layer.stateMachine.states = [];
+    //     }
+    //     if (state.hash === undefined) {
+    //         state.hash = stringToHash(state.name || "state" + layer.stateMachine.states.length);
+    //     }
+
+    // }
+
+
     /**
      * The normalized time (0-1) to start playing the first state at.
      * This affects the initial state when the animator is first enabled.
@@ -331,7 +350,7 @@ export class AnimatorController {
      * The Animator component this controller is bound to.
      */
     animator?: Animator;
-    
+
     /**
      * The data model describing the animation states and transitions.
      */

package/src/engine-components/CameraUtils.ts

@@ -117,16 +117,15 @@ function createDefaultCameraControls(context: IContext, cam?: ICamera) {
     if (cameraObject) {
         const orbit = getOrAddComponent(cameraObject, OrbitControls) as OrbitControls;
         orbit.sourceId = cam?.sourceId ?? "unknown";
+        // /enable auto-rotate if the auto-rotate attribute is provided
         const autoRotate = context.domElement.getAttribute("auto-rotate");
-        orbit.autoRotate = autoRotate !== undefined && autoRotate !== null && (autoRotate != "0" && autoRotate?.toLowerCase() != "false");
-        orbit.autoRotateSpeed = 0.5;
-        orbit.autoFit = true;
-        if (orbit.autoRotate && autoRotate) {
-            const autoRotateValue = parseFloat(autoRotate);
-            if (!isNaN(autoRotateValue)) {
-                orbit.autoRotateSpeed = autoRotateValue;
-            }
-        }
+        orbit.autoRotate = autoRotate != "0" && autoRotate?.toLowerCase() != "false";
+        const autoRotateSpeed = Number.parseFloat(autoRotate || ".5");
+        orbit.autoRotateSpeed = !isNaN(autoRotateSpeed) ? autoRotateSpeed : .5;
+        console.log("Auto-rotate", orbit.autoRotate, "speed:", orbit.autoRotateSpeed);
+        const autoFit = context.domElement.getAttribute("auto-fit");
+        orbit.autoFit = autoFit !== "0" && autoFit?.toLowerCase() != "false";
+        orbit.autoTarget = true;
     }
     else {
         console.warn("Missing camera object, can not add orbit controls")

package/src/engine-components/OrbitControls.ts

@@ -2,18 +2,19 @@ import { Camera as Camera3, Object3D, PerspectiveCamera, Ray, Vector2, Vector3,
 import { OrbitControls as ThreeOrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
 
 import { isDevEnvironment } from "../engine/debug/index.js";
+import { fitCamera, FitCameraOptions } from "../engine/engine_camera.fit.js";
 import { setCameraController } from "../engine/engine_camera.js";
 import { Gizmos } from "../engine/engine_gizmos.js";
 import { InputEventQueue, NEPointerEvent } from "../engine/engine_input.js";
 import { Mathf } from "../engine/engine_math.js";
 import { IRaycastOptions, RaycastOptions } from "../engine/engine_physics.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
-import { getBoundingBox, getTempVector, getWorldPosition } from "../engine/engine_three_utils.js";
+import { getTempVector, getWorldPosition } from "../engine/engine_three_utils.js";
 import type { ICameraController } from "../engine/engine_types.js";
 import { DeviceUtilities, getParam } from "../engine/engine_utils.js";
+import { NeedleEngineWebComponent } from "../engine/webcomponents/needle-engine.js";
 import { Camera } from "./Camera.js";
 import { Behaviour, GameObject } from "./Component.js";
-import { GroundProjectedEnv } from "./GroundProjection.js";
 import { LookAtConstraint } from "./LookAtConstraint.js";
 import { SyncedTransform } from "./SyncedTransform.js";
 import { type AfterHandleInputEvent, EventSystem, EventSystemEvents } from "./ui/EventSystem.js";
@@ -354,6 +355,9 @@ export class OrbitControls extends Behaviour implements ICameraController {
         if (debug) console.debug("OrbitControls", this);
         this._didSetTarget = 0;
         this._startedListeningToKeyEvents = false;
+        if ((this.context.domElement as NeedleEngineWebComponent).cameraControls === false) {
+            this.enabled = false;
+        }
     }
 
     /** @internal */
@@ -490,10 +494,13 @@ export class OrbitControls extends Behaviour implements ICameraController {
                 this._lastTimeClickOnBackground = this.context.time.time;
                 if (this.clickBackgroundToFitScene <= 1 || dt < this.clickBackgroundToFitScene * .15) {
                     this._clickOnBackgroundCount += 1;
-                    if (this._clickOnBackgroundCount >= this.clickBackgroundToFitScene - 1)
-                        this.fitCamera(this.context.scene.children, {
-                            immediate: false
+                    if (this._clickOnBackgroundCount >= this.clickBackgroundToFitScene - 1) {
+                        this.autoRotate = false;
+                        this.fitCamera({
+                            objects: this.context.scene,
+                            immediate: false,
                         });
+                    }
                 }
                 else {
                     this._clickOnBackgroundCount = 0;
@@ -530,7 +537,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
     private _orbitStartAngle: number = 0;
     private _zoomStartDistance: number = 0;
     private onControlsChangeStarted = () => {
-        if(debug) console.debug("OrbitControls: Change started");
+        if (debug) console.debug("OrbitControls: Change started");
         if (this._controls) {
             this._orbitStartAngle = this._controls.getAzimuthalAngle() + this._controls.getPolarAngle();
             this._zoomStartDistance = this._controls.getDistance();
@@ -540,7 +547,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
         }
     }
     private onControlsChangeEnded = () => {
-        if(debug) console.debug("OrbitControls: Change ended", { autoTarget: this.autoTarget });
+        if (debug) console.debug("OrbitControls: Change ended", { autoTarget: this.autoTarget });
         if (this._controls) {
             if (this.autoTarget) {
                 const newAngle = this._controls.getAzimuthalAngle() + this._controls.getPolarAngle();
@@ -989,242 +996,26 @@ export class OrbitControls extends Behaviour implements ICameraController {
     /** 
      * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in) 
     */
-    fitCamera(options?: FitCameraOptions);
-    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<FitCameraOptions, "objects">);
-    fitCamera(objectsOrOptions?: Object3D | Array<Object3D> | FitCameraOptions, options?: FitCameraOptions): void {
-
-        if (this.context.isInXR) {
-            // camera fitting in XR is not supported
-            console.warn('[OrbitControls] Can not fit camera while XR session is active');
-            return;
-        }
-
-        let objects: Object3D | Array<Object3D> | undefined = undefined;
-        // If the user passed in an array as first argument
-        if (Array.isArray(objectsOrOptions)) {
-            objects = objectsOrOptions;
-        }
-        // If the user passed in an object as first argument
-        else if (objectsOrOptions && "type" in objectsOrOptions) {
-            objects = objectsOrOptions;
-        }
-        // If the user passed in an object as first argument and options as second argument
-        else if (objectsOrOptions && typeof objectsOrOptions === "object") {
-            if (!(objectsOrOptions instanceof Object3D) && !Array.isArray(objectsOrOptions)) {
-                options = objectsOrOptions;
-                objects = options.objects;
-            }
-        }
-        // Ensure objects are setup correctly
-        if (objects && !Array.isArray(objects)) {
-            objects = [objects];
-        }
-        if (!Array.isArray(objects) || objects && objects.length <= 0) {
-            objects = this.context.scene.children;
-        }
-
-        // Make sure there's anything to fit to
-        if (!Array.isArray(objects) || objects.length <= 0) {
-            console.warn("No objects to fit camera to...");
-            return;
-        }
-
-        const camera = this._cameraObject as PerspectiveCamera;
-        const controls = this._controls as ThreeOrbitControls | null;
-
-        if (!camera || !controls) {
-            console.warn("No camera or controls found to fit camera to objects...");
-            return;
-        }
-        if (!options) options = {}
-        const { immediate = false, centerCamera, cameraNearFar = "auto", fitOffset = 1.1, fov = camera?.fov } = options;
-        const size = new Vector3();
-        const center = new Vector3();
-        // TODO would be much better to calculate the bounds in camera space instead of world space - 
-        // we would get proper view-dependant fit.
-        // Right now it's independent from where the camera is actually looking from,
-        // and thus we're just getting some maximum that will work for sure.
-        const box = getBoundingBox(objects, undefined, this._camera?.threeCamera?.layers);
-        const boxCopy = box.clone();
-        box.getCenter(center);
-
-        const box_size = new Vector3();
-        box.getSize(box_size);
-
-        // project this box into camera space
-        camera.updateMatrixWorld();
-        box.applyMatrix4(camera.matrixWorldInverse);
-
-        box.getSize(size);
-        box.setFromCenterAndSize(center, size);
-        if (Number.isNaN(size.x) || Number.isNaN(size.y) || Number.isNaN(size.z)) {
-            console.warn("Camera fit size resultet in NaN", camera, box, [...objects]);
-            return;
-        }
-        if (size.length() <= 0.0000000001) {
-            if (debugCameraFit) console.warn("Camera fit size is zero", box, [...objects]);
-            return;
-        }
-
-        const verticalFov = fov;
-        const horizontalFov = 2 * Math.atan(Math.tan(verticalFov * Math.PI / 360 / 2) * camera.aspect) / Math.PI * 360;
-        const fitHeightDistance = size.y / (2 * Math.atan(Math.PI * verticalFov / 360));
-        const fitWidthDistance = size.x / (2 * Math.atan(Math.PI * horizontalFov / 360));
-
-        const distance = fitOffset * Math.max(fitHeightDistance, fitWidthDistance) + size.z / 2;
-
-        if (debugCameraFit) {
-            console.log("Fit camera to objects", { fitHeightDistance, fitWidthDistance, distance, verticalFov, horizontalFov });
-        }
-
-        this.maxZoom = distance * 10;
-        this.minZoom = distance * 0.01;
-
-        const verticalOffset = 0.05;
-        const lookAt = center.clone();
-        lookAt.y -= size.y * verticalOffset;
-        if (options.targetOffset) {
-            if (options.targetOffset.x !== undefined) lookAt.x += options.targetOffset.x;
-            if (options.targetOffset.y !== undefined) lookAt.y += options.targetOffset.y;
-            if (options.targetOffset.z !== undefined) lookAt.z += options.targetOffset.z;
-        }
-        if (options.relativeTargetOffset) {
-            if (options.relativeTargetOffset.x !== undefined) lookAt.x += options.relativeTargetOffset.x * size.x;
-            if (options.relativeTargetOffset.y !== undefined) lookAt.y += options.relativeTargetOffset.y * size.y;
-            if (options.relativeTargetOffset.z !== undefined) lookAt.z += options.relativeTargetOffset.z * size.z;
-        }
-        this.setLookTargetPosition(lookAt, immediate);
-        this.setFieldOfView(options.fov, immediate);
-
-        if (cameraNearFar == undefined || cameraNearFar == "auto") {
-            // Check if the scene has a GroundProjectedEnv and include the scale to the far plane so that it doesnt cut off
-            const groundprojection = GameObject.findObjectOfType(GroundProjectedEnv);
-            const groundProjectionRadius = groundprojection ? groundprojection.radius : 0;
-            const boundsMax = Math.max(box_size.x, box_size.y, box_size.z, groundProjectionRadius);
-            // TODO: this doesnt take the Camera component nearClipPlane into account
-            camera.near = (distance / 100);
-            camera.far = boundsMax + distance * 10;
-            camera.updateProjectionMatrix();
-
-            // adjust maxZoom so that the ground projection radius is always inside
-            if (groundprojection) {
-                this.maxZoom = Math.max(Math.min(this.maxZoom, groundProjectionRadius * 0.5), distance);
-            }
-        }
-
-        // ensure we're not clipping out of the current zoom level just because we're fitting
-        const currentZoom = controls.getDistance();
-        if (currentZoom < this.minZoom) this.minZoom = currentZoom * 0.9;
-        if (currentZoom > this.maxZoom) this.maxZoom = currentZoom * 1.1;
-
-        const direction = center.clone();
-        if (options.fitDirection) {
-            direction.sub(new Vector3().copy(options.fitDirection).multiplyScalar(1_000_000));
-        }
-        else {
-            direction.sub(camera.worldPosition);
-        }
-        if (centerCamera === "y")
-            direction.y = 0;
-        direction.normalize();
-        direction.multiplyScalar(distance);
-        if (centerCamera === "y")
-            direction.y += -verticalOffset * 4 * distance;
-
-        let cameraLocalPosition = center.clone().sub(direction);
-        if (options.cameraOffset) {
-            if (options.cameraOffset.x !== undefined) cameraLocalPosition.x += options.cameraOffset.x;
-            if (options.cameraOffset.y !== undefined) cameraLocalPosition.y += options.cameraOffset.y;
-            if (options.cameraOffset.z !== undefined) cameraLocalPosition.z += options.cameraOffset.z;
-        }
-        if (options.relativeCameraOffset) {
-            if (options.relativeCameraOffset.x !== undefined) cameraLocalPosition.x += options.relativeCameraOffset.x * size.x;
-            if (options.relativeCameraOffset.y !== undefined) cameraLocalPosition.y += options.relativeCameraOffset.y * size.y;
-            if (options.relativeCameraOffset.z !== undefined) cameraLocalPosition.z += options.relativeCameraOffset.z * size.z;
-        }
-        if (camera.parent) {
-            cameraLocalPosition = camera.parent.worldToLocal(cameraLocalPosition);
-        }
-        this.setCameraTargetPosition(cameraLocalPosition, immediate);
-
-        if (debugCameraFit || options.debug) {
-            Gizmos.DrawWireBox3(box, 0xffff33, 10);
-            Gizmos.DrawWireBox3(boxCopy, 0x00ff00, 10);
-
-            if (!this._haveAttachedKeyboardEvents && debugCameraFit) {
-                this._haveAttachedKeyboardEvents = true;
-                document.body.addEventListener("keydown", (e) => {
-                    if (e.code === "KeyF") {
-                        // random fov for easier debugging of fov-based fitting
-                        let fov: number | undefined = undefined;
-                        if (this._cameraObject instanceof PerspectiveCamera) fov = (Math.random() * Math.random()) * 170 + 10;
-                        this.fitCamera({ objects, fitOffset, immediate: false, fov });
-                    }
-                    if (e.code === "KeyV") {
-                        if (this._cameraObject instanceof PerspectiveCamera) this._cameraObject.fov = 60;
-                    }
-                });
-            }
-        }
-
+    fitCamera(options?: OrbitFitCameraOptions): void {
+        const res = fitCamera({
+            ...options,
+            autoApply: false,
+            context: this.context,
+            camera: this._cameraObject as Camera3,
+            currentZoom: this._controls?.getDistance() || undefined,
+            minZoom: this.minZoom,
+            maxZoom: this.maxZoom,
+        });
+        if (!res) return;
+        this.setLookTargetPosition(res.lookAt, options?.immediate || false);
+        this.setCameraTargetPosition(res.position, options?.immediate || false);
+        this.setFieldOfView(options?.fov, options?.immediate || false);
         this.onBeforeRender();
-        // controls.update(); // this is not enough when calling fitCamera({immediate:true}) in an interval
     }
 
     private _haveAttachedKeyboardEvents: boolean = false;
 }
 
-
-/**
- * Options for fitting the camera to the scene. Used in {@link OrbitControls.fitCamera}
- */
-export type FitCameraOptions = {
-    /** When enabled debug rendering will be shown */
-    debug?: boolean,
-    /**
-     * The objects to fit the camera to. If not provided the scene children will be used
-     */
-    objects?: Object3D[] | Object3D;
-    /** If true the camera will move immediately to the new position, otherwise it will lerp 
-     * @default false
-     */
+type OrbitFitCameraOptions = FitCameraOptions & {
     immediate?: boolean,
-
-    /** Fit offset: A factor to multiply the distance to the objects by
-     * @default 1.1
-     */
-    fitOffset?: number,
-
-    /** The direction from which the camera should be fitted in worldspace. If not defined the current camera's position will be used */
-    fitDirection?: Vector3Like,
-
-    /** If set to "y" the camera will be centered in the y axis */
-    centerCamera?: "none" | "y",
-    /** Set to 'auto' to update the camera near or far plane based on the fitted-objects bounds */
-    cameraNearFar?: "keep" | "auto",
-
-    /**
-     * Offset the camera position in world space
-     */
-    cameraOffset?: Partial<Vector3Like>,
-    /**
-     * Offset the camera position relative to the size of the objects being focused on (e.g. x: 0.5).  
-     * Value range: -1 to 1
-     */
-    relativeCameraOffset?: Partial<Vector3Like>,
-
-    /**
-     * Offset the camera target position in world space
-     */
-    targetOffset?: Partial<Vector3Like>,
-    /**
-     * Offset the camera target position relative to the size of the objects being focused on.  
-     * Value range: -1 to 1
-     */
-    relativeTargetOffset?: Partial<Vector3Like>,
-
-    /**
-     * Field of view (FOV) for the camera
-     */
-    fov?: number,
-}
+}

package/src/engine-components/api.ts

@@ -53,7 +53,6 @@ import "./AnimationUtilsAutoplay.js"
 
 export { DragMode } from "./DragControls.js";
 export type { DropListenerNetworkEventArguments, DropListenerOnDropArguments } from "./DropListener.js";
-export { type FitCameraOptions } from "./OrbitControls.js";
 export * from "./particlesystem/api.js"
 export * from "./splines/index.js";
 export * from "./web/index.js";

package/src/engine-components/codegen/components.ts

@@ -205,6 +205,7 @@ export { VideoPlayer } from "../VideoPlayer.js";
 export { Voip } from "../Voip.js";
 export { ClickThrough } from "../web/Clickthrough.js";
 export { CursorFollow } from "../web/CursorFollow.js";
+export { HoverAnimation } from "../web/HoverAnimation.js";
 export { ScrollFollow } from "../web/ScrollFollow.js";
 export { Avatar } from "../webxr/Avatar.js";
 export { XRControllerFollow } from "../webxr/controllers/XRControllerFollow.js";

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

@@ -21,6 +21,9 @@ onStart(ctx => {
  * - 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
+ * @category Web
+ * @group Components
+ * @component
  */
 export class ClickThrough extends Behaviour {
 

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

@@ -4,6 +4,9 @@ import { Behaviour } from "../Component.js";
 
 /**
  * The CursorFollow component makes the object follow the cursor (or touch) position on screen.
+ * @category Web
+ * @group Components
+ * @component
  */
 export class CursorFollow extends Behaviour {
 

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

@@ -0,0 +1,99 @@
+import { AnimationClip } from "three";
+
+import { ScaleClipType } from "../../engine/engine_animation.js";
+import { AnimationUtils } from "../../engine/engine_animation.js";
+import { serializable } from "../../engine/engine_serialization_decorator.js";
+import { registerType } from "../../engine/engine_typestore.js";
+import { Animation } from "../Animation.js";
+import { Behaviour } from "../Component.js";
+
+
+/**
+ * @category Web
+ * @group Components
+ * @component
+ */
+@registerType
+export class HoverAnimation extends Behaviour {
+
+    /**
+     * Default hover animation type if no custom clip is provided.  
+     * **Node**: This is only used if no custom hover animation clip is provided.  
+     * @default "linear"
+     */
+    @serializable()
+    type: ScaleClipType = "linear";
+
+    /**
+     * Duration of the hover animation in seconds.  
+     * **Node**: This is only used if no custom hover animation clip is provided.
+     * @default 0.1
+     */
+    @serializable()
+    duration: number = 0.1;
+
+    /**
+     * Scale factor to apply when hovering.  
+     * **Node**: This is only used if no custom hover animation clip is provided.
+     * @default 1.1
+     */
+    @serializable()
+    scaleFactor: number = 1.1;
+
+
+    /**
+     * Animation clip to play when hovering. If null, a default scale-up animation is used.
+     */
+    @serializable(AnimationClip)
+    hovered: AnimationClip | null = null;
+
+    /**
+     * Animation clip to play when not hovering. If null, an empty clip is used.
+     */
+    @serializable(AnimationClip)
+    idle: AnimationClip | null = null;
+
+    private animation: Animation | null = null;
+
+    start() {
+        if (!this.idle) this.idle = AnimationUtils.emptyClip();
+
+        if (!this.hovered) {
+            this.hovered = AnimationUtils.createScaleClip({
+                type: "linear",
+                duration: this.duration || 0.1,
+                scale: this.gameObject.scale,
+                scaleFactor: this.scaleFactor || 1.1,
+            });
+        }
+
+        this.animation ??= this.gameObject.addComponent(Animation);
+        this.animation.playAutomatically = false;
+        this.playIdle();
+    }
+
+    onEnable() {
+        if (this.animation) this.animation.enabled = true;
+        this.playIdle();
+    }
+    onDisable() {
+        if (this.animation) this.animation.enabled = false;
+        this.playIdle();
+    }
+
+    onPointerEnter() {
+        this.playHover();
+    }
+
+    onPointerExit() {
+        this.playIdle();
+    }
+
+    private playIdle() {
+        if (this.idle) this.animation?.play(this.idle, { exclusive: true, fadeDuration: .1, loop: true });
+    }
+    private playHover() {
+        if (this.hovered) this.animation?.play(this.hovered, { exclusive: true, fadeDuration: .1, loop: false, clampWhenFinished: true });
+    }
+
+}

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

@@ -44,6 +44,10 @@ type ScrollFollowEvent = {
  * 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.
+ * 
+ * @category Web
+ * @group Components
+ * @component
  */
 export class ScrollFollow extends Behaviour {
 

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

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