@needle-tools/engine 5.1.9 → 5.1.10

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/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/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 { $Ljyi } 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 (!$Ljyi()) {
             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 (!$Ljyi()) {
                             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 (!$Ljyi()) {
             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/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;

package/src/engine-components/webxr/controllers/XRControllerModel.ts

@@ -1,7 +1,6 @@
 import { AxesHelper, Group, Material, Mesh, Object3D, XRHandSpace } from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { XRControllerModelFactory } from "three/examples/jsm/webxr/XRControllerModelFactory.js";
-import { XRHandMeshModel } from "three/examples/jsm/webxr/XRHandMeshModel.js";
 
 import { AssetReference } from "../../../engine/engine_addressables.js";
 import { setDontDestroy } from "../../../engine/engine_gameobject.js";
@@ -15,6 +14,7 @@ import { NeedleXRController, type NeedleXRControllerEventArgs, type NeedleXREven
 import { registerComponentExtension, registerExtensions } from "../../../engine/extensions/extensions.js";
 import { NEEDLE_progressive } from "../../../engine/extensions/NEEDLE_progressive.js";
 import { flipForwardMatrix } from "../../../engine/xr/internal.js";
+import { XRHandMeshModel } from "../../../engine/xr/XRHandMeshModel.js";
 import { Behaviour, Component, GameObject } from "../../Component.js"
 
 const debug = getParam("debugwebxr");
@@ -288,8 +288,6 @@ export class XRControllerModel extends Behaviour {
 
         const loader = new GLTFLoader();
         addDracoAndKTX2Loaders(loader, context);
-        await registerExtensions(loader, context, this.sourceId ?? "", this.sourceId ?? "");
-        const componentsExtension = registerComponentExtension(loader);
 
         let filename = "";
 
@@ -306,22 +304,30 @@ export class XRControllerModel extends Behaviour {
             loader.setPath('https://cdn.jsdelivr.net/npm/@webxr-input-profiles/assets@1.0/dist/profiles/generic-hand/');
         }
 
+        // The hand is a separate glTF and needs its own source id: its components resolve their
+        // relative uris against it (resolveUrl) and its lightmaps/skybox are keyed by it. Using
+        // this component's id resolved the hand's uris next to the HOST glb and let the hand's
+        // skybox overwrite the scene's. customHand.url is already resolved, `filename` is not
+        // (extension stripped for XRHandMeshModel).
+        const handSourceId = customHand?.url ?? `${loader.path}${filename}.glb`;
+        await registerExtensions(loader, context, handSourceId, handSourceId);
+        const componentsExtension = registerComponentExtension(loader);
+
 
         const handObject = new Object3D();
         setDontDestroy(handObject);
-        // @ts-ignore
         const handmesh = new XRHandMeshModel(handObject, hand, loader.path, filename, loader, (object: Object3D) => {
 
             const gltf = componentsExtension?.gltf;
-            // The XRHandMeshController removes the hand from the gltf before calling this callback
-            // we need this in the GLTF scene however for creating the builtin components 
+            // XRHandMeshModel reparents the hand out of the gltf scene before calling this
+            // callback; we need it back in the scene so the builtin components are created on it
             if (gltf?.scene.children?.length === 0) {
                 gltf.scene.children[0] = object;
             }
 
             // console.log(controller.side, componentsExtension.gltf, object, componentsExtension.gltf.scene?.children)
             if (componentsExtension?.gltf)
-                getLoader().createBuiltinComponents(comp.context, comp.sourceId || filename, componentsExtension.gltf, null, componentsExtension);
+                getLoader().createBuiltinComponents(comp.context, handSourceId, componentsExtension.gltf, null, componentsExtension);
 
             // The hand mesh should not receive raycasts
             object.traverse(child => {