@needle-tools/engine 5.1.9 → 5.1.11

package/src/engine/webcomponents/needle-engine.ts

@@ -3,7 +3,7 @@ import type { Texture } from "three";
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
-import { _$qxlHFE, Telemetry } from "../engine_license.js";
+import { __zrAx, Telemetry } from "../engine_license.js";
 import { onStart } from "../engine_lifecycle_api.js";
 import { setDracoDecoderPath, setDracoDecoderType, setKtx2TranscoderPath } from "../engine_loaders.gltf.js";
 import { Context, ContextCreateArgs } from "../engine_setup.js";
@@ -579,7 +579,7 @@ export class NeedleEngineWebComponent extends HTMLElementBase implements INeedle
 
 
         // Loading start events
-        const allowOverridingDefaultLoading = _$qxlHFE();
+        const allowOverridingDefaultLoading = __zrAx();
         // default loading can be overriden by calling preventDefault in the onload start event
         this.ensureLoadStartIsRegistered();
         let useDefaultLoading = this.dispatchEvent(new CustomEvent("loadstart", {

package/src/engine/xr/TempXRContext.ts

@@ -3,7 +3,7 @@ import { ArrayCamera, AxesHelper, Camera, Color, DirectionalLight, Fog, GridHelp
 import { needleLogoOnlySVG } from "../assets/index.js";
 import { isDevEnvironment } from "../debug/index.js";
 import { ObjectUtils, PrimitiveType } from "../engine_create_objects.js";
-import { _$qxlHFE } from "../engine_license.js";
+import { __zrAx } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { delay, DeviceUtilities } from "../engine_utils.js";
 
@@ -215,7 +215,7 @@ export class TemporaryXRContext {
         this._scene.background = new Color(0x000000);
 
         let logoSrc = needleLogoOnlySVG;
-        if (_$qxlHFE()) {
+        if (__zrAx()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");

package/src/engine/xr/XRHandMeshModel.ts

@@ -0,0 +1,179 @@
+import { type Bone, type Object3D, type XRHandSpace } from "three";
+import type { GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+
+/**
+ * Vendored from three's `examples/jsm/webxr/XRHandMeshModel.js` (r185).
+ *
+ * WHY THIS IS OWNED BY THE ENGINE AND NOT PATCHED IN THE THREE FORK
+ * -----------------------------------------------------------------
+ * three addons carry no API stability guarantee and this one changed under us twice:
+ *
+ *  - r184 replaced `const object = gltf.scene.children[0]` with
+ *    `const object = clone(gltf.scene.children[0])`. That single word broke every custom
+ *    (Unity-exported) hand model, silently: `SkeletonUtils.clone` runs `Object3D.copy`,
+ *    which deep-copies userData via `JSON.parse(JSON.stringify(...))`. Needle stores live
+ *    component instances in `userData.components`, and components hold a `gameObject`
+ *    back-reference, so that throws "Converting circular structure to JSON" — swallowed by
+ *    GLTFLoader into an onError nobody had set, leaving an empty, invisible hand.
+ *  - The clone also broke component creation: `XRControllerModel` creates the glTF's builtin
+ *    components after load, but the parser's node -> object associations point at the parsed
+ *    original while the clone is what gets displayed.
+ *
+ * DELIBERATE DIFFERENCES FROM UPSTREAM
+ * ------------------------------------
+ *  1. No clone. Upstream needs it only because of `customCache`, where several hands share
+ *     one parsed gltf. We never pass a cache and build a fresh GLTFLoader per hand load, so
+ *     nothing is shared and the clone was pure overhead. Using the parsed object directly
+ *     restores the pre-r184 contract the engine is written against: `handModel.add(object)`
+ *     reparents it out of `gltf.scene` (Object3D.add calls removeFromParent), object identity
+ *     is preserved so the parser's node map stays valid, and components created during parse
+ *     live on the object that is actually rendered.
+ *  2. `customCache` is dropped entirely rather than left unused — sharing a parsed hand
+ *     between models would reintroduce the aliasing the clone existed to prevent.
+ *  3. The hand mesh inherits the layer mask of the object it is added to (the engine puts
+ *     hands on the ignore-raycast layer).
+ *  4. Load failures are reported instead of vanishing.
+ *  5. A missing SkinnedMesh or missing joints no longer throw / spam per joint.
+ *
+ * When bumping three, diff this against the upstream file and fold in real fixes by hand.
+ */
+
+const DEFAULT_HAND_PROFILE_PATH = "https://cdn.jsdelivr.net/npm/@webxr-input-profiles/assets@1.0/dist/profiles/generic-hand/";
+
+/** The joints of a WebXR hand, in the order three's hand models declare them. */
+const JOINT_NAMES = [
+    "wrist",
+    "thumb-metacarpal",
+    "thumb-phalanx-proximal",
+    "thumb-phalanx-distal",
+    "thumb-tip",
+    "index-finger-metacarpal",
+    "index-finger-phalanx-proximal",
+    "index-finger-phalanx-intermediate",
+    "index-finger-phalanx-distal",
+    "index-finger-tip",
+    "middle-finger-metacarpal",
+    "middle-finger-phalanx-proximal",
+    "middle-finger-phalanx-intermediate",
+    "middle-finger-phalanx-distal",
+    "middle-finger-tip",
+    "ring-finger-metacarpal",
+    "ring-finger-phalanx-proximal",
+    "ring-finger-phalanx-intermediate",
+    "ring-finger-phalanx-distal",
+    "ring-finger-tip",
+    "pinky-finger-metacarpal",
+    "pinky-finger-phalanx-proximal",
+    "pinky-finger-phalanx-intermediate",
+    "pinky-finger-phalanx-distal",
+    "pinky-finger-tip",
+] as const;
+
+type JointBone = Bone & { jointName?: string };
+
+/**
+ * Renders a skinned hand mesh and drives its bones from the tracked WebXR joint poses.
+ *
+ * @see {@link XRControllerModel} which creates one per tracked hand.
+ */
+export class XRHandMeshModel {
+
+    /** The three XRHandSpace whose `joints` drive this mesh. */
+    readonly controller: XRHandSpace;
+    /** The object the loaded hand mesh is added to. */
+    readonly handModel: Object3D;
+    /** The bones driven by {@link updateMesh}, in {@link JOINT_NAMES} order. Sparse if the model lacks joints. */
+    readonly bones: Array<JointBone | undefined> = [];
+
+    /**
+     * @param handModel the object the loaded mesh is parented to
+     * @param controller the hand space providing joint poses
+     * @param path base path for the model (defaults to the generic hand profile CDN)
+     * @param handedness file name to load (without extension) — either "left"/"right" for the
+     *                   default profile, or a full path for a custom hand model
+     * @param loader loader to use; a plain GLTFLoader is created when omitted
+     * @param onLoad invoked with the loaded hand object once it has been added
+     */
+    constructor(
+        handModel: Object3D,
+        controller: XRHandSpace,
+        path: string | null,
+        handedness: string,
+        loader: GLTFLoader | null = null,
+        onLoad: ((object: Object3D) => void) | null = null,
+    ) {
+        this.controller = controller;
+        this.handModel = handModel;
+
+        const pathToUse = path || DEFAULT_HAND_PROFILE_PATH;
+
+        if (loader === null) {
+            loader = new GLTFLoader();
+            loader.setPath(pathToUse);
+        }
+
+        const url = `${handedness}.glb`;
+        loader.load(url,
+            (gltf: GLTF) => {
+                const object = gltf.scene.children[0];
+                if (!object) {
+                    console.error(`XRHandMeshModel: "${pathToUse}${url}" contains no hand object.`);
+                    return;
+                }
+
+                // NOTE: adding reparents `object` out of `gltf.scene` (Object3D.add calls
+                // removeFromParent), which is what lets the caller detect that the hand has
+                // been taken over and create the glTF's builtin components on it.
+                this.handModel.add(object);
+                // the hand mesh inherits the layers of whatever it was added to
+                object.layers.mask = this.handModel.layers.mask;
+
+                const mesh = object.getObjectByProperty("type", "SkinnedMesh");
+                if (mesh) {
+                    mesh.frustumCulled = false;
+                    mesh.castShadow = true;
+                    mesh.receiveShadow = true;
+                }
+                else {
+                    console.warn(`XRHandMeshModel: no SkinnedMesh in the ${handedness} hand model — it will not deform.`);
+                }
+
+                const missing: string[] = [];
+                for (const jointName of JOINT_NAMES) {
+                    const bone = object.getObjectByName(jointName) as JointBone | undefined;
+                    if (bone) bone.jointName = jointName;
+                    else missing.push(jointName);
+                    this.bones.push(bone);
+                }
+                // one warning instead of one per joint — a model with the wrong rig misses all 25
+                if (missing.length) {
+                    console.warn(`XRHandMeshModel: the ${handedness} hand model is missing ${missing.length} of ${JOINT_NAMES.length} joints (${missing.join(", ")}).`);
+                }
+
+                onLoad?.(object);
+            },
+            undefined,
+            (err: unknown) => {
+                // Upstream passes no error handler, so a failed hand model silently leaves an
+                // empty object and no hand is ever visible. Surface it instead.
+                console.error(`XRHandMeshModel: failed to load the ${handedness} hand model from "${pathToUse}${url}" — the hand will not be visible.`, err);
+            });
+    }
+
+    /** Copies the current tracked joint poses onto the mesh bones. Called every XR frame. */
+    updateMesh() {
+        const XRJoints = this.controller.joints;
+
+        for (let i = 0; i < this.bones.length; i++) {
+            const bone = this.bones[i];
+            if (!bone?.jointName) continue;
+
+            const XRJoint = XRJoints[bone.jointName];
+            if (XRJoint?.visible) {
+                bone.position.copy(XRJoint.position);
+                bone.quaternion.copy(XRJoint.quaternion);
+            }
+        }
+    }
+}

package/src/engine-components/DragControls.ts

@@ -197,13 +197,6 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
     @serializable()
     public xrDistanceDragFactor: number = 1;
 
-    /** 
-     * When enabled, draws a visual line from the dragged object downwards to the next raycast hit,
-     * providing visual feedback about the object's position relative to surfaces below it.
-     */
-    @serializable()
-    public showGizmo: boolean = false;
-
     /** Drag profile for screen / touch / mouse input. Reads live from the flat serialized fields. */
     readonly screenProfile: DragProfile = new DragProfile(this, false);
     /** Drag profile for XR tracked-pointer and transient-pointer input. Reads live from the flat `xr*` serialized fields. */

package/src/engine-components/ReflectionProbe.ts

@@ -289,9 +289,9 @@ export class ReflectionProbe extends Behaviour {
         if (block) {
             const current = block.getOverride("envMap")?.value;
             if (current === this.texture) {
-                block.removeOveride("envMap");
-                block.removeOveride("envMapRotation");
-                block.removeOveride("envMapIntensity");
+                block.removeOverride("envMap");
+                block.removeOverride("envMapRotation");
+                block.removeOverride("envMapIntensity");
             }
         }
     }

package/src/engine-components/RendererInstancing.ts

@@ -1,5 +1,5 @@
 import { calculateMeshLODLevel, getLODColor } from "@needle-tools/gltf-progressive";
-import { BatchedMesh, BufferGeometry, Color, Material, Matrix4, Mesh, MeshStandardMaterial, Object3D, RawShaderMaterial, Vector3 } from "three";
+import { BatchedMesh, BufferGeometry, Color, Material, Matrix4, Mesh, MeshStandardMaterial, Object3D, RawShaderMaterial, Sphere, Vector3 } from "three";
 
 import { isDevEnvironment, showBalloonError } from "../engine/debug/index.js";
 import { Gizmos } from "../engine/engine_gizmos.js";
@@ -25,6 +25,11 @@ function trackProgressiveLOD<T>(context: Context, type: "mesh" | "texture", obje
     return promise;
 }
 
+/** Mirrored = negative determinant, which reverses triangle winding. */
+function isMirrored(matrix: Matrix4): boolean {
+    return matrix.determinant() < 0;
+}
+
 /**
  * Handles instancing for Needle Engine.
  */
@@ -108,8 +113,12 @@ export class InstancingHandler {
             const mat = mesh.material as Material | Material[];
             if (Array.isArray(mat)) return null;
 
+            // mirrored objects need their own batch, see InstancedMeshRenderer
+            mesh.updateWorldMatrix(true, false);
+            const mirrored = isMirrored(mesh.matrixWorld);
+
             for (const i of this.objs) {
-                if (!i.canAdd(geometry, mat)) continue;
+                if (!i.canAdd(geometry, mat, mirrored)) continue;
                 const handle = i.addInstance(mesh, geometry);
                 return handle;
             }
@@ -119,7 +128,7 @@ export class InstancingHandler {
             }
             let name = obj.name;
             if (!name?.length) name = makeIdFromRandomWords();
-            const i = new InstancedMeshRenderer(name, geometry, mat, maxInstances, context);
+            const i = new InstancedMeshRenderer(name, geometry, mat, maxInstances, context, mirrored);
             this.objs.push(i);
             const handle = i.addInstance(mesh, geometry);
             return handle;
@@ -240,8 +249,18 @@ export class InstanceHandle {
     updateInstanceMatrix(updateChildren: boolean = false, updateMatrix: boolean = true) {
         if (this.__instanceIndex < 0) return;
         if (updateMatrix) this.object.updateWorldMatrix(true, updateChildren);
+        this.assertMirroringUnchanged();
         this.renderer.updateInstance(this.object.matrixWorld, this.__instanceIndex);
     }
+
+    private _didWarnAboutMirroringChange = false;
+    /** Batches are bucketed by mirroring at setup time and an instance can not move between them. */
+    private assertMirroringUnchanged() {
+        if (this._didWarnAboutMirroringChange) return;
+        if (isMirrored(this.object.matrixWorld) === this.renderer.mirrored) return;
+        this._didWarnAboutMirroringChange = true;
+        console.warn(`[Instancing] "${this.name}" changed its mirroring at runtime (world matrix determinant flipped sign). Instanced objects can not change mirroring - this object will render its backfaces. Disable instancing for it via Renderer.setInstanced(obj, false).`);
+    }
     /** Updates the matrix of the instance */
     setMatrix(matrix: Matrix4) {
         if (this.__instanceIndex < 0) return;
@@ -320,6 +339,23 @@ export class InstanceHandle {
     }
 }
 
+/**
+ * Renders one geometry+material combination for many objects using a
+ * {@link https://threejs.org/docs/#api/en/objects/BatchedMesh | BatchedMesh}.
+ *
+ * The BatchedMesh belongs to this class: it is created here, parented directly to the untransformed
+ * `context.scene` and never moved, so its transform is whatever {@link applyBatchTransform} puts
+ * there and nothing else.
+ *
+ * **Mirroring:** three flips the winding for a mirrored transform per *draw call*, from
+ * `object.matrixWorld.determinant()` - and for a batch that object is the BatchedMesh, not the
+ * instance. So mirrored instances get their own batch, which carries the mirror on its own
+ * transform (`scale.z = -1`); otherwise their front faces would be culled.
+ *
+ * That mirror is the one transform the shader's `modelMatrix * batchingMatrix` would otherwise apply
+ * twice, so a mirrored batch stores its instance matrices with it undone. Every other batch is
+ * untransformed and stores world matrices as they are.
+ */
 class InstancedMeshRenderer {
     /** The three instanced mesh
      * @link https://threejs.org/docs/#api/en/objects/InstancedMesh
@@ -327,6 +363,11 @@ class InstancedMeshRenderer {
     get batchedMesh() {
         return this._batchedMesh;
     }
+
+    /** True if this batch renders mirrored objects. A batch only holds one or the other. */
+    get mirrored() {
+        return this._mirrored;
+    }
     get visible(): boolean {
         return this._batchedMesh.visible;
     }
@@ -369,15 +410,17 @@ class InstancedMeshRenderer {
         if (sphere)
             this._batchedMesh.computeBoundingSphere();
         if (debugInstancing && this._batchedMesh.boundingSphere) {
-            const sphere = this._batchedMesh.boundingSphere;
-            // const worldPos = this._batchedMesh.worldPosition.add(sphere.center);
-            // const worldRadius = sphere!.radius;
+            // the bounding sphere is in the batch's local space, the gizmo expects world space
+            const sphere = InstancedMeshRenderer.debugBoundsSphere
+                .copy(this._batchedMesh.boundingSphere)
+                .applyMatrix4(this._batchedMesh.matrixWorld);
             Gizmos.DrawWireSphere(sphere.center, sphere.radius, 0x00ff00);
         }
     }
 
     private _context: Context;
     private _batchedMesh: BatchedMesh;
+    private readonly _mirrored: boolean;
     private _handles: (InstanceHandle | null)[] = [];
     private _geometryIds = new WeakMap<BufferGeometry, number>();
     private _maxInstanceCount: number;
@@ -389,8 +432,9 @@ class InstancedMeshRenderer {
     private _maxVertexCount: number;
     private _maxIndexCount: number;
 
-    private static nullMatrix: Matrix4 = new Matrix4();
+    private static instanceMatrix: Matrix4 = new Matrix4();
     private static lodProjectionScreenMatrix: Matrix4 = new Matrix4();
+    private static debugBoundsSphere: Sphere = new Sphere();
     private static debugLODColor = new Color();
     private static lodSelectionResult = {
         level: -1,
@@ -403,12 +447,15 @@ class InstancedMeshRenderer {
     /** Check if the geometry can be added to this instancer
      * @param geometry The geometry to check
      * @param material The material of the geometry
+     * @param mirrored Whether the object's world matrix has a negative determinant
      * @returns true if the geometry can be added
      */
-    canAdd(geometry: BufferGeometry, material: Material): boolean {
+    canAdd(geometry: BufferGeometry, material: Material, mirrored: boolean): boolean {
 
         if (this._maxVertexCount > 10_000_000) return false;
 
+        if (this._mirrored !== mirrored) return false;
+
         // The material instance must match
         // perhaps at some point later we *could* check if it's the same shader and properties but this would be risky
         if (material !== this.material) {
@@ -482,11 +529,12 @@ class InstancedMeshRenderer {
         return this.name ? `${this.name} (BatchedMesh)` : "BatchedMesh";
     }
 
-    constructor(name: string, geo: BufferGeometry, material: Material, initialMaxCount: number, context: Context) {
+    constructor(name: string, geo: BufferGeometry, material: Material, initialMaxCount: number, context: Context, mirrored: boolean = false) {
         this.name = name;
         this.geometry = geo;
         this.material = material;
         this._context = context;
+        this._mirrored = mirrored;
         this._maxInstanceCount = Math.max(2, initialMaxCount);
         if (debugInstancing) {
             this._debugMaterial = createDebugMaterial(debugLODColors);
@@ -496,6 +544,7 @@ class InstancedMeshRenderer {
         this._maxIndexCount = estimate.indexCount;
         this._batchedMesh = new BatchedMesh(this._maxInstanceCount, this._maxVertexCount, this._maxIndexCount, this._debugMaterial ?? this.material);
         this._batchedMesh.name = this.getBatchedMeshName();
+        this.applyBatchTransform(this._batchedMesh);
         // this.inst = new InstancedMesh(geo, material, count);
         this._batchedMesh[$instancingAutoUpdateBounds] = true;
         // this.inst.count = 0;
@@ -614,10 +663,39 @@ class InstancedMeshRenderer {
     }
 
     updateInstance(mat: Matrix4, index: number) {
-        this._batchedMesh.setMatrixAt(index, mat);
+        this.setInstanceMatrix(index, mat);
         this.markNeedsUpdate();
     }
 
+    /** The batch's own transform. This class owns it: the mirror is the only thing that ever goes
+     * here, and the batch is never reparented away from the untransformed scene root. */
+    private applyBatchTransform(batch: BatchedMesh) {
+        // every other batch keeps the identity a fresh BatchedMesh is constructed with
+        if (!this._mirrored) return;
+        if (batch.scale.z === -1) return;
+        // negative determinant on the batch itself -> three flips the winding for the whole draw call
+        batch.scale.z = -1;
+        // three composes the TRS into matrix/matrixWorld no earlier than the render, which would leave
+        // those identity for a frame - and updateBounds() reads matrixWorld from a pre-render callback
+        batch.updateMatrixWorld();
+    }
+
+    /** Writes a *world* matrix to an instance slot, converted into the batch's local space.
+     * All instance matrix writes go through here. */
+    private setInstanceMatrix(index: number, worldMatrix: Matrix4) {
+        if (!this._mirrored) {
+            // an untransformed batch: local space *is* world space
+            this._batchedMesh.setMatrixAt(index, worldMatrix);
+            return;
+        }
+        // undo the batch's mirror, so the shader's modelMatrix * batchingMatrix composes back to the world matrix.
+        // a pure z flip only negates row 2 (column-major indices 2/6/10/14), so it's cheaper than a full multiply
+        const local = InstancedMeshRenderer.instanceMatrix.copy(worldMatrix);
+        const e = local.elements;
+        e[2] = -e[2]; e[6] = -e[6]; e[10] = -e[10]; e[14] = -e[14];
+        this._batchedMesh.setMatrixAt(index, local);
+    }
+
     updateGeometry(geo: BufferGeometry, geometryIndex: number): boolean {
         if (!this.validateGeometry(geo)) {
             return false;
@@ -815,11 +893,14 @@ class InstancedMeshRenderer {
         newInst.receiveShadow = this._batchedMesh.receiveShadow;
         newInst.visible = this._batchedMesh.visible;
         newInst[$instancingAutoUpdateBounds] = this._batchedMesh[$instancingAutoUpdateBounds];
+
         newInst.matrixAutoUpdate = this._batchedMesh.matrixAutoUpdate;
         newInst.matrixWorldNeedsUpdate = this._batchedMesh.matrixWorldNeedsUpdate;
         newInst.matrixAutoUpdate = this._batchedMesh.matrixAutoUpdate;
         newInst.matrixWorld.copy(this._batchedMesh.matrixWorld);
         newInst.matrix.copy(this._batchedMesh.matrix);
+        // the replacement must carry the mirror too, otherwise every instance in it ends up culled
+        this.applyBatchTransform(newInst);
 
         // dispose the old batched mesh
         this._batchedMesh.dispose();
@@ -942,7 +1023,7 @@ class InstancedMeshRenderer {
         handle.__instanceIndex = i;
         handle.__reservedVertexRange = handle.maxVertexCount;
         handle.__reservedIndexRange = handle.maxIndexCount;
-        this._batchedMesh.setMatrixAt(i, handle.object.matrixWorld);
+        this.setInstanceMatrix(i, handle.object.matrixWorld);
         this.updateDebugLODColor(handle);
         if (debugInstancing)
             console.debug(`[Instancing] > ADDED INSTANCE \"${handle.name}\"\nGEOMETRY_ID=${geometryId}\n${this._currentInstanceCount} instances\nIndex: ${handle.__instanceIndex}\nVertices: ${this._currentVertexCount.toLocaleString()}/${this._maxVertexCount.toLocaleString()},\nIndices: ${this._currentIndexCount.toLocaleString()}/${this._maxIndexCount.toLocaleString()}`);

package/src/engine-components/RendererLightmap.ts

@@ -146,7 +146,7 @@ export class RendererLightmap {
         }
         const block = MaterialPropertyBlock.get(this.gameObject);
         if (block) {
-            block.removeOveride("lightMap");
+            block.removeOverride("lightMap");
         }
     }
 

package/src/engine-components/SyncedRoom.ts

@@ -190,6 +190,11 @@ export class SyncedRoom extends Behaviour {
             if (val && (typeof val === "string" || typeof val === "number")) {
                 hasRoomParameter = true;
                 const roomNameParam = utils.sanitizeString(val.toString());
+                // The URL parameter takes precedence over the configured roomName. That is
+                // easy to miss when a room name was set deliberately, so say so in dev.
+                if ((debug || isDevEnvironment()) && this.roomName?.length > 0 && this.roomName !== roomNameParam) {
+                    console.warn(`[SyncedRoom] Joining "${roomNameParam}" from the "${this.urlParameterName}" URL parameter — the roomName set on the component ("${this.roomName}") is ignored.\nThe URL parameter always wins. To use the component's room name instead, clear "urlParameterName".`);
+                }
                 this.roomName = roomNameParam;
             }
             else if (this.joinRandomRoom) {

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -3,7 +3,7 @@ import { Euler, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "t
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { findObjectOfType } from "../../../engine/engine_components.js";
-import { _iXmRJVD } from "../../../engine/engine_license.js";
+import { oMxKl } from "../../../engine/engine_license.js";
 import { serializable } from "../../../engine/engine_serialization.js";
 import { getFormattedDate, Progress } from "../../../engine/engine_time_utils.js";
 import { DeviceUtilities, getParam } from "../../../engine/engine_utils.js";
@@ -277,7 +277,7 @@ export class USDZExporter extends Behaviour {
         let name = this.exportFileName ?? this.objectToExport?.name ?? this.name;
         name += "-" + getFormattedDate(); // seems iOS caches the file in some cases, this ensures we always have a fresh file
 
-        if (!_iXmRJVD()) {
+        if (!oMxKl()) {
             if (name !== "") name += "-";
             name += "MadeWithNeedle";
         }
@@ -682,7 +682,7 @@ export class USDZExporter extends Behaviour {
                     if (debug)
                         showBalloonMessage("Quicklook url: " + callToActionURL);
                     if (callToActionURL) {
-                        if (!_iXmRJVD()) {
+                        if (!oMxKl()) {
                             console.warn("Quicklook closed: custom redirects require a Needle Engine Pro license: https://needle.tools/pricing", callToActionURL)
                         }
                         else {
@@ -697,7 +697,7 @@ export class USDZExporter extends Behaviour {
     private buildQuicklookOverlay(): CustomBranding {
         const obj: CustomBranding = {};
         if (this.customBranding) Object.assign(obj, this.customBranding);
-        if (!_iXmRJVD()) {
+        if (!oMxKl()) {
             console.log("Custom Quicklook banner text requires pro license: https://needle.tools/pricing");
             obj.callToAction = "Close";
             obj.checkoutTitle = "🌵 Made with Needle";

package/src/engine-components/postprocessing/Effects/DepthOfField.ts

@@ -83,12 +83,20 @@ export class DepthOfField extends PostProcessingEffect {
         //     inverted: true,
         //     // blendFunction: BlendFunction.SET,
         // });
+        // Seed from the parameters, the same way BloomEffect does. The
+        // onValueChanged handlers below only fire on a LATER assignment, so
+        // hardcoding defaults here discarded anything set before the effect
+        // was created — which is the usual case, since components are
+        // configured right after addComponent but the effect is built when
+        // the composer asks for it. Values applied in awake/start were lost
+        // and only took hold if the same value was assigned a second time.
         const dof = new MODULES.POSTPROCESSING.MODULE.DepthOfFieldEffect(this.context.mainCamera!, {
-            worldFocusRange: .2,
+            worldFocusRange: this.focalLength.value,
             focalLength: 1,
-            bokehScale: 20,
+            bokehScale: this.aperture.value,
             resolutionScale: this.resolutionScale.value,
         });
+        dof.cocMaterial.worldFocusDistance = this.focusDistance.value;
 
         this.focusDistance.onValueChanged = v => {
             dof.cocMaterial.worldFocusDistance = v;

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

@@ -1,6 +1,13 @@
 export * from "./PostProcessingEffect.js";
 export * from "./PostProcessingHandler.js"
 export { PostProcessingEffectOrder } from "./utils.js";
+/* Effect option enums. The effect components themselves are exported from
+   codegen/components.ts, but these were unreachable: `DepthOfField.mode`
+   could not be set to a named value from outside the package. */
+export { DepthOfFieldMode } from "./Effects/DepthOfField.js";
+export { QualityLevel } from "./Effects/Antialiasing.js";
+export { ScreenSpaceAmbientOcclusionN8QualityMode } from "./Effects/ScreenspaceAmbientOcclusionN8.js";
+export { NEToneMappingMode } from "./Effects/Tonemapping.utils.js";
 export { PostProcessingManager } from "./Volume.js"
 export { Volume } from "./Volume.js"
 export * from "./VolumeParameter.js"

package/src/engine-components/splines/SplineWalker.ts

@@ -74,7 +74,11 @@ export class SplineWalker extends Behaviour {
         return this._position01;
     }
     set position01(v: number) {
-        this._position01 = v;
+        // Normalize on assignment so reading the value back is predictable and never out of range.
+        // Doing this only in updateFromPosition() made it depend on a spline + curve + object being
+        // ready and a frame having run — until then this property reported e.g. 1.5.
+        // Note this is destructive (as clamping always is): setting 1.5 while clamped stores 1.
+        this._position01 = this.clamp ? Mathf.clamp01(v) : Mathf.repeat(v);
         this._needsUpdate = true;
     }
 
@@ -156,10 +160,12 @@ export class SplineWalker extends Behaviour {
         if (!this.spline || !this.spline.curve) return;
         if (!this.object) return;
 
+        // Still normalized here as well: autoRun accumulates into _position01 directly (bypassing the
+        // setter), and `clamp` may change after a value was assigned.
         if (this.clamp) this._position01 = Mathf.clamp01(this._position01);
-        else this._position01 = this._position01 % 1;
+        else this._position01 = Mathf.repeat(this._position01);
 
-        const t = this._position01 >= 1 ? 1 : this._position01 % 1;
+        const t = this._position01 >= 1 ? 1 : Mathf.repeat(this._position01);
         const pt = this.spline.getPointAt(t);
 
         if (this.pullStrength >= 1) {

package/src/engine-components/utils/LookAt.ts

@@ -20,25 +20,34 @@ import { Behaviour } from "../Component.js";
 export class LookAt extends Behaviour implements UsdzBehaviour {
 
     /**
-     * The target object to look at. If not set, the main camera will be used.
+     * The target object to look at.
+     * @default undefined — when no target is set the main camera is used
      */
     @serializable(Object3D)
     target?: Object3D;
 
     /**
-     * Inverts the forward direction.
+     * Inverts the forward direction, so the object turns its back to the target
+     * instead of facing it. Useful for models authored facing -Z.
+     * @default false
      */
     @serializable()
     invertForward: boolean = false;
 
     /**
-     * Keep the up direction.
+     * Keeps the object upright while turning, so it only rotates around the up
+     * axis rather than tilting to point directly at a target above or below it.
+     * @default true
      */
     @serializable()
     keepUpDirection: boolean = true;
 
     /**
-     * Copy the target rotation.
+     * Copies the target's rotation instead of aiming at its position. Use this to
+     * match a target's orientation, for example to align with the camera.
+     *
+     * Ignored during a VR or AR session.
+     * @default false
      */
     @serializable()
     copyTargetRotation: boolean = false;

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

@@ -520,7 +520,7 @@ export class WebXR extends Behaviour {
             models = this.gameObject.addComponent(XRControllerModel)!;
             this._createdComponentsInSession.push(models);
             models.createControllerModel = this.showControllerModels;
-            models.createHandModel == this.showHandModels;
+            models.createHandModel = this.showHandModels;
         }
         if (models) models.enabled = enabled;
         return models;