@needle-tools/engine 5.1.10 → 5.1.12

package/dist/needle-engine.d.ts

@@ -116,19 +116,19 @@ import { XRHandSpace } from 'three';
 
 export declare const $componentName: unique symbol;
 
-/* Excluded from this release type: $fHATZ */
-
-/* Excluded from this release type: $Ljyi */
+/* Excluded from this release type: _$EHSDVcNK */
 
 export declare const $physicsKey: unique symbol;
 
+/* Excluded from this release type: $uxbFepO */
+
+/* Excluded from this release type: _$VfAckLjB */
+
 export declare class __Ignore {
 }
 
 export declare function __internalNotifyObjectDestroyed(obj: Object3D): void;
 
-/* Excluded from this release type: __KODK */
-
 /** Data describing the accessible semantics for a 3D object or component. */
 declare type AccessibilityData = {
     /** ARIA role (e.g. `"button"`, `"img"`, `"region"`). */
@@ -5904,11 +5904,6 @@ export declare class DragControls extends Component implements IPointerEventHand
      * This is similar to mouse acceleration on a screen.
      */
     xrDistanceDragFactor: number;
-    /**
-     * 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.
-     */
-    showGizmo: boolean;
     /** Drag profile for screen / touch / mouse input. Reads live from the flat serialized fields. */
     readonly screenProfile: DragProfile;
     /** Drag profile for XR tracked-pointer and transient-pointer input. Reads live from the flat `xr*` serialized fields. */
@@ -9494,11 +9489,30 @@ export declare class InputField extends Component implements IPointerEventHandle
     private processInputOniOS;
 }
 
+/**
+ * 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.
+ */
 declare class InstancedMeshRenderer {
     /** The three instanced mesh
      * @link https://threejs.org/docs/#api/en/objects/InstancedMesh
      */
     get batchedMesh(): BatchedMesh;
+    /** True if this batch renders mirrored objects. A batch only holds one or the other. */
+    get mirrored(): boolean;
     get visible(): boolean;
     set visible(val: boolean);
     get castShadow(): boolean;
@@ -9521,6 +9535,7 @@ declare class InstancedMeshRenderer {
     updateBounds(box?: boolean, sphere?: boolean): void;
     private _context;
     private _batchedMesh;
+    private readonly _mirrored;
     private _handles;
     private _geometryIds;
     private _maxInstanceCount;
@@ -9529,25 +9544,33 @@ declare class InstancedMeshRenderer {
     private _currentIndexCount;
     private _maxVertexCount;
     private _maxIndexCount;
-    private static nullMatrix;
+    private static instanceMatrix;
     private static lodProjectionScreenMatrix;
+    private static debugBoundsSphere;
     private static debugLODColor;
     private static lodSelectionResult;
     /** 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;
     private _needUpdateBounds;
     private _debugMaterial;
     private getBatchedMeshName;
-    constructor(name: string, geo: BufferGeometry, material: Material, initialMaxCount: number, context: Context);
+    constructor(name: string, geo: BufferGeometry, material: Material, initialMaxCount: number, context: Context, mirrored?: boolean);
     dispose(): void;
     addInstance(obj: Mesh, geometry?: BufferGeometry): InstanceHandle | null;
     add(handle: InstanceHandle): boolean;
     remove(handle: InstanceHandle, delete_: boolean): void;
     updateInstance(mat: Matrix4, index: number): void;
+    /** 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;
+    /** Writes a *world* matrix to an instance slot, converted into the batch's local space.
+     * All instance matrix writes go through here. */
+    private setInstanceMatrix;
     updateGeometry(geo: BufferGeometry, geometryIndex: number): boolean;
     private onBeforeRender;
     private updateProgressiveMeshLODs;
@@ -9605,6 +9628,9 @@ export declare class InstanceHandle {
     updateMeshInformation(): boolean;
     /** Updates the matrix from the rendered object. Will also call updateWorldMatrix internally */
     updateInstanceMatrix(updateChildren?: boolean, updateMatrix?: boolean): void;
+    private _didWarnAboutMirroringChange;
+    /** Batches are bucketed by mirroring at setup time and an instance can not move between them. */
+    private assertMirroringUnchanged;
     /** Updates the matrix of the instance */
     setMatrix(matrix: Matrix4): void;
     /** Can be used to change the geometry of this instance */
@@ -11630,6 +11656,19 @@ declare class MathHelper {
      * @returns Value clamped to [0, 1]
      */
     clamp01(value: number): number;
+    /**
+     * Loops a value so that it never exceeds `length` and never goes below 0 — the modulo you
+     * usually want for wrapping. Note that JavaScript's `%` operator is a *remainder*: it keeps the
+     * sign of the dividend, so `-0.25 % 1` is `-0.25`, not `0.75`. This returns `0.75`.
+     * @param value Value to wrap
+     * @param length Length of the range to wrap into (defaults to 1)
+     * @returns Value wrapped into [0, length)
+     * @example ```javascript
+     * Mathf.repeat(1.5, 1); // 0.5
+     * Mathf.repeat(-0.25, 1); // 0.75
+     * ```
+     */
+    repeat(value: number, length?: number): number;
     /**
      * Linearly interpolates between two values.
      * @param value1 Start value (returned when t=0)