@needle-tools/engine 5.1.10 → 5.1.11

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