@needle-tools/engine 4.17.0-alpha.4 → 4.17.0-alpha.6

package/plugins/vite/asap.js

@@ -227,6 +227,10 @@ function insertPreloadLink(tags, href, type) {
         attrs: {
             rel: "preload",
             as: "fetch",
+            // Use low priority so glTF/GLB downloads don't compete with JS chunks
+            // for bandwidth. The engine JS must load first to render anything;
+            // the GLB still starts downloading early but yields bandwidth to scripts.
+            fetchpriority: "low",
             href: href,
             type: type,
             crossorigin: true,

package/plugins/vite/build-pipeline.js

@@ -210,6 +210,19 @@ export async function needleBuildPipeline(command, config, userSettings) {
                     const moved = getDirectoryStats(buildPipelineTaskResults.tempDirectory);
                     const ctx = { count: 0, bytes: 0 }
                     copyFilesSync(buildPipelineTaskResults.tempDirectory, buildPipelineTaskResults.outputDirectory, true, ctx);
+                    // Clean up source files that were replaced by the build pipeline
+                    // (e.g. .exr files that now have .pmrem.ktx2 replacements)
+                    const outputDir = buildPipelineTaskResults.outputDirectory;
+                    try {
+                        for (const file of readdirSync(outputDir)) {
+                            if (file.endsWith('.exr')) {
+                                const replacement = file.replace(/\.exr$/i, '.pmrem.ktx2');
+                                if (existsSync(outputDir + '/' + replacement)) {
+                                    rmSync(outputDir + '/' + file);
+                                }
+                            }
+                        }
+                    } catch { /* silent */ }
                     lines.push(`${key("Copying compressed results")}: "${outputPath}" — ${moved.fileCount} file${moved.fileCount !== 1 ? 's' : ''}, ${formatBytes(moved.totalBytes)}`);
                 }
                 else {

package/plugins/vite/dependencies.js

@@ -131,7 +131,7 @@ function handleManualChunks(config) {
             isVite8 = parseInt(JSON.parse(readFileSync(vitePkgPath, 'utf8')).version) >= 8;
         }
     } catch { }
-    needleLog("needle-dependencies", `Vite 8+ detected: ${isVite8}`);
+    if (isVite8) needleLog("needle-dependencies", `Vite 8+ detected`);
 
     if (Array.isArray(rollupOutput)) {
         // append the manualChunks function to the array

package/plugins/vite/poster-client.js

@@ -7,7 +7,7 @@ async function generatePoster() {
         // Keep in sync with og:image:width meta tags
         // https://developers.facebook.com/docs/sharing/best-practices/
         const width = 1080;
-        const height = 1080;
+        const height = width * (9 / 16);
 
         return new Promise(res => {
             /** @ts-ignore */

package/src/engine-components/AlignmentConstraint.ts

@@ -29,7 +29,6 @@ import { Behaviour, GameObject } from "./Component.js";
  * @summary Aligns and scales object between two targets
  * @category Constraints
  * @group Components
- * @see {@link LookAtConstraint} for rotation-only constraints
  * @see {@link SmoothFollow} for following with smoothing
  **/
 export class AlignmentConstraint extends Behaviour {

package/src/engine-components/BasicIKConstraint.ts

@@ -31,7 +31,6 @@ import { Behaviour, GameObject } from "./Component.js";
  * @summary Two-bone inverse kinematics constraint
  * @category Animation and Sequencing
  * @group Components
- * @see {@link LookAtConstraint} for aim constraints
  * @see {@link AlignmentConstraint} for simpler alignment
  */
 export class BasicIKConstraint extends Behaviour {

package/src/engine-components/LookAtConstraint.ts

@@ -1,58 +1,7 @@
-import { Object3D, Vector3 } from "three";
-
-import { serializable } from "../engine/engine_serialization_decorator.js";
-import type { LookAt } from "./api.js";
 import { Behaviour } from "./Component.js";
-import type { OrbitControls } from "./OrbitControls.js";
 
 /**
- * The [LookAtConstraint](https://engine.needle.tools/docs/api/LookAtConstraint) component is primarely used by {@link OrbitControls} to set the camera's focus point.
- * It does not have its own logic to update the look-at position.  
- *
- * The constraint uses a list of source objects - the look-at target is  
- * calculated from the first source in the `sources` array.  
- *
- * **Integration with OrbitControls:**  
- * When attached to the same GameObject as OrbitControls, this constraint  
- * controls where the camera orbits around and looks at.  
- *
- * @summary Look At Constraint for camera targeting
- * @category Camera and Controls
- * @group Components
- * @see {@link OrbitControls} for camera orbit controls
- * @see {@link SmoothFollow} for smooth position/rotation following
- * @see {@link LookAt} for directly making an object look at a target without using a constraint
+ * @deprecated LookAtConstraint has been removed. Use a plain Object3D/Transform reference on OrbitControls instead.
  */
 export class LookAtConstraint extends Behaviour {
-
-    /**
-     * When true, the constraint is active and affects the target.
-     * Set to false to temporarily disable without removing sources.
-     */
-    @serializable()
-    constraintActive: boolean = true;
-
-    /**
-     * When true, the look-at position is locked and won't update
-     * even if source objects move.
-     */
-    @serializable()
-    locked: boolean = false;
-
-    /**
-     * Objects to look at. The first object in the array is used
-     * as the primary look-at target.
-     */
-    @serializable(Object3D)
-    sources: Object3D[] = [];
-
-    /**
-     * Sets the world position that the constraint should look at.
-     * Updates the first source object's position.
-     * @param worldPosition The world-space position to look at
-     */
-    setConstraintPosition(worldPosition: Vector3) {
-        const source = this.sources[0];
-        if (source) source.worldPosition = worldPosition;
-    }
-}
+}

package/src/engine-components/OffsetConstraint.ts

@@ -32,7 +32,6 @@ import { Behaviour, GameObject } from "./Component.js";
  * @category Constraints
  * @group Components
  * @see {@link SmoothFollow} for smoothed following
- * @see {@link LookAtConstraint} for aim constraints
  * @see {@link AlignmentConstraint} for alignment between two objects
  */
 export class OffsetConstraint extends Behaviour {

package/src/engine-components/OrbitControls.ts

@@ -15,7 +15,6 @@ 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 { LookAtConstraint } from "./LookAtConstraint.js";
 import { SyncedTransform } from "./SyncedTransform.js";
 import { type AfterHandleInputEvent, EventSystem, EventSystemEvents } from "./ui/EventSystem.js";
 import { tryGetUIComponent } from "./ui/Utils.js";
@@ -99,7 +98,6 @@ declare module 'three/examples/jsm/controls/OrbitControls.js' {
  * @summary Camera controller using three.js OrbitControls
  * @category Camera and Controls
  * @group Components
- * @see {@link LookAtConstraint} for setting the look-at target
  * @see {@link SmoothFollow} for smooth camera following
  * @see {@link Camera} for camera configuration
  * @link https://threejs.org/docs/#examples/en/controls/OrbitControls
@@ -228,12 +226,19 @@ export class OrbitControls extends Behaviour implements ICameraController {
      */
     @serializable()
     enablePan: boolean = true;
-    /** Assigning a {@link LookAtConstraint} will make the camera look at the constraint source 
+    /** Assigning an Object3D will make the camera look at this target's position.
+     * The camera will orbit around this target.
      * @default null
     */
-    @serializable(LookAtConstraint)
-    lookAtConstraint: LookAtConstraint | null = null;
-    /** The weight of the first lookAtConstraint source 
+    @serializable(Object3D)
+    lookAtTarget: Object3D | null = null;
+    /** When enabled the camera will continuously follow the lookAtTarget's position every frame.
+     * When disabled the target is only used for the initial look direction.
+     * @default true
+    */
+    @serializable()
+    lockLookAtTarget: boolean = true;
+    /** The weight for the lookAtTarget interpolation
      * @default 1
     */
     @serializable()
@@ -392,11 +397,13 @@ export class OrbitControls extends Behaviour implements ICameraController {
     private _camera: Camera | null = null;
     private _syncedTransform?: SyncedTransform;
     private _didSetTarget = 0;
+    private _didApplyLookAtTarget = false;
 
     /** @internal */
     awake(): void {
         if (debug) console.debug("OrbitControls", this);
         this._didSetTarget = 0;
+        this._didApplyLookAtTarget = false;
         this._startedListeningToKeyEvents = false;
         if ((this.context.domElement as NeedleEngineWebComponent).cameraControls === false) {
             this.enabled = false;
@@ -421,6 +428,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
     /** @internal */
     onEnable() {
         this._didSetTarget = 0;
+        this._didApplyLookAtTarget = false;
         this._enableTime = this.context.time.time;
         const cameraComponent = GameObject.getComponent(this.gameObject, Camera);
         this._camera = cameraComponent;
@@ -565,6 +573,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
     };
 
     private updateTargetNow(options?: IRaycastOptions) {
+        if(debug) console.warn("OrbitControls: updateTargetNow is using raycasting to update the target immediately. This can be expensive and should be used with caution.", options);
         const ray = new Ray(this._cameraObject?.worldPosition, this._cameraObject?.worldForward.multiplyScalar(-1));
         const hits = this.context.physics.raycastFromRay(ray, options);
         const hit = hits.length > 0 ? hits[0] : undefined;
@@ -807,8 +816,14 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
             // this._controls.zoomToCursor = this.zoomToCursor;
             if (!this.context.isInXR) {
-                if (!freeCam && this.lookAtConstraint?.locked && !this._lookTargetLerpActive) {
-                    this.setLookTargetFromConstraint(0, this.lookAtConstraint01);
+                if (!freeCam && this.lookAtTarget && !this._lookTargetLerpActive) {
+                    if (this.lockLookAtTarget) {
+                        this.setLookTargetFromConstraint(this.lookAtConstraint01);
+                    }
+                    else if (!this._didApplyLookAtTarget) {
+                        this._didApplyLookAtTarget = true;
+                        this.setLookTargetFromConstraint(1);
+                    }
                 }
                 this._controls.update(this.context.time.deltaTime);
 
@@ -1011,30 +1026,22 @@ export class OrbitControls extends Behaviour implements ICameraController {
         this._lookTargetLerpActive = false;
     }
 
-    /** Sets the look at target from an assigned lookAtConstraint source by index 
-     * @param index The index of the source to use
+    /** Sets the look at target from the assigned lookAtTarget Object3D
      * @param t The interpolation factor between the current look at target and the new target
     */
-    private setLookTargetFromConstraint(index: number = 0, t: number = 1): boolean {
+    private setLookTargetFromConstraint(t: number = 1): boolean {
         if (!this._controls) return false;
-        if (this.lookAtConstraint?.enabled === false) return false;
-        const sources = this.lookAtConstraint?.sources;
-        if (sources && sources.length > 0) {
-            const target = sources[index];
-            if (target) {
-                target.getWorldPosition(this._lookTargetEndPosition);
-                this.lerpLookTarget(this._controls.target, this._lookTargetEndPosition, t);
-                return true;
-            }
-        }
-        return false;
+        if (!this.lookAtTarget) return false;
+        this.lookAtTarget.getWorldPosition(this._lookTargetEndPosition);
+        this.lerpLookTarget(this._controls.target, this._lookTargetEndPosition, t);
+        return true;
     }
 
     private lerpLookTarget(start: Vector3, position: Vector3, t: number) {
         if (!this._controls) return;
         if (t >= 1) this._controls.target.copy(position);
         else this._controls.target.lerpVectors(start, position, t);
-        if (this.lookAtConstraint) this.lookAtConstraint.setConstraintPosition(this._controls.target);
+        if (this.lookAtTarget && this.lockLookAtTarget) this.lookAtTarget.worldPosition = this._controls.target;
     }
 
     private setTargetFromRaycast(ray?: Ray, immediateOrDuration: number | boolean = false): boolean {

package/src/engine-components/SmoothFollow.ts

@@ -54,7 +54,6 @@ import { Behaviour } from "./Component.js";
  * @summary Smoothly follows a target object's position and/or rotation
  * @category Interactivity
  * @group Components
- * @see {@link LookAtConstraint} for making an object look at a target (different from rotation following)
  * @see {@link Mathf} for the interpolation used
  */
 export class SmoothFollow extends Behaviour {

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

@@ -78,7 +78,6 @@ const debug = getParam("debugcursor");
  *
  * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/) - Combines CursorFollow with LookAt for an interactive 3D header
  *
- * @see {@link LookAtConstraint} - Commonly combined with CursorFollow for look-at effects
  * @see {@link PointerEvents} - For more complex pointer interaction handling
  * @see {@link DragControls} - For dragging objects in 3D space
  * @see {@link OrbitControls} - For camera controls that work alongside CursorFollow

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

@@ -12,7 +12,6 @@ import { RGBAColor } from "../../engine/js-extensions/RGBAColor.js";
 import type { Camera as CameraComponent } from "../Camera.js";
 import { Behaviour } from "../Component.js";
 import type { DragControls } from "../DragControls.js";
-import type { LookAtConstraint } from "../LookAtConstraint.js";
 import type { OrbitControls } from "../OrbitControls.js";
 import type { SceneSwitcher } from "../SceneSwitcher.js";
 
@@ -93,7 +92,6 @@ export type ViewBoxMode = "continuous" | "once";
  * @see {@link CameraComponent} - The camera component that ViewBox controls
  * @see {@link OrbitControls} - Camera controls that work alongside ViewBox
  * @see {@link DragControls} - Alternative camera controls compatible with ViewBox
- * @see {@link LookAtConstraint} - Another way to control camera targeting
  * @see {@link SceneSwitcher} - Can be combined with ViewBox for scene transitions
  * @see {@link Context.setCameraFocusRect} - The underlying focus rect API used by ViewBox
  * @see {@link Context.focusRectSettings} - Manual control of focus rect settings