@needle-tools/engine 5.1.9 → 5.1.11

package/dist/needle-engine.d.ts

@@ -5,6 +5,7 @@ import { Audio as Audio_2 } from 'three';
 import { AudioListener as AudioListener_3 } from 'three';
 import { BatchedMesh } from 'three';
 import { BloomEffect as BloomEffect_2 } from 'postprocessing';
+import { Bone } from 'three';
 import { Box3 } from 'three';
 import { BufferGeometry } from 'three';
 import { Camera as Camera_2 } from 'three';
@@ -111,22 +112,21 @@ import { WebGLRenderTarget } from 'three';
 import { WebXRArrayCamera } from 'three';
 import { World } from '@dimforge/rapier3d-compat';
 import { XRControllerModelFactory } from 'three/examples/jsm/webxr/XRControllerModelFactory.js';
-import { XRHandMeshModel } from 'three/examples/jsm/webxr/XRHandMeshModel.js';
 import { XRHandSpace } from 'three';
 
 export declare const $componentName: unique symbol;
 
-/* Excluded from this release type: $iNNlsg */
-
 export declare const $physicsKey: unique symbol;
 
-/* Excluded from this release type: _$qxlHFE */
-
 export declare class __Ignore {
 }
 
 export declare function __internalNotifyObjectDestroyed(obj: Object3D): void;
 
+/* Excluded from this release type: __nlZsk */
+
+/* Excluded from this release type: __zrAx */
+
 /** Data describing the accessible semantics for a 3D object or component. */
 declare type AccessibilityData = {
     /** ARIA role (e.g. `"button"`, `"img"`, `"region"`). */
@@ -5567,7 +5567,7 @@ export declare class DepthOfField extends PostProcessingEffect {
     unapply(): void;
 }
 
-declare enum DepthOfFieldMode {
+export declare enum DepthOfFieldMode {
     Off = 0,
     Gaussian = 1,
     Bokeh = 2
@@ -5902,11 +5902,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. */
@@ -9492,11 +9487,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;
@@ -9519,6 +9533,7 @@ declare class InstancedMeshRenderer {
     updateBounds(box?: boolean, sphere?: boolean): void;
     private _context;
     private _batchedMesh;
+    private readonly _mirrored;
     private _handles;
     private _geometryIds;
     private _maxInstanceCount;
@@ -9527,25 +9542,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;
@@ -9603,6 +9626,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 */
@@ -10458,8 +10484,6 @@ export declare interface IWatch {
     dispose(): any;
 }
 
-/* Excluded from this release type: _iXmRJVD */
-
 export declare interface IXRRig extends Pick<IComponent, "gameObject"> {
     isXRRig(): boolean;
     get isActive(): boolean;
@@ -10502,6 +10526,10 @@ declare abstract class Joint extends Component {
     protected abstract createJoint(self: Rigidbody, other: Rigidbody): any;
 }
 
+declare type JointBone = Bone & {
+    jointName?: string;
+};
+
 /** Locks the follow object's world rotation to the quaternion captured at drag-start. */
 export declare class KeepRotationConstraint implements IDragConstraint {
     private readonly _savedQuat;
@@ -11050,19 +11078,28 @@ export declare enum LogType {
  */
 export declare class LookAt extends Component 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
      */
     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
      */
     invertForward: boolean;
     /**
-     * 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
      */
     keepUpDirection: boolean;
     /**
-     * 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
      */
     copyTargetRotation: boolean;
     private static flipYQuat;
@@ -11256,7 +11293,7 @@ export declare class MaskableGraphic extends Graphic {
  * This means:
  * - If you change the object's material, the overrides will still be applied to the new material
  * - Multiple objects can share the same material but have different property overrides
- * - If you don't want overrides applied after changing a material, you must remove them using {@link removeOveride}, {@link clearAllOverrides}, or {@link dispose}
+ * - If you don't want overrides applied after changing a material, you must remove them using {@link removeOverride}, {@link clearAllOverrides}, or {@link dispose}
  *
  * The property block system works by:
  * - Temporarily applying overrides in onBeforeRender
@@ -11318,7 +11355,7 @@ export declare class MaskableGraphic extends Graphic {
  * // If you don't want overrides on the new material, remove them:
  * block.clearAllOverrides(); // Remove all overrides
  * // or
- * block.removeOveride("color"); // Remove specific override
+ * block.removeOverride("color"); // Remove specific override
  * // or
  * block.dispose(); // Remove the entire property block
  * ```
@@ -11445,11 +11482,20 @@ export declare class MaterialPropertyBlock<T extends Material = Material> {
      * block.setOverride("lightMap", lightmapTexture);
      *
      * // Remove a specific override - the material will now use its original color
-     * block.removeOveride("color");
+     * block.removeOverride("color");
      *
      * // Other overrides (roughness, lightMap) remain active
      * ```
      */
+    removeOverride<K extends NonFunctionPropertyNames<T>>(name: K | ({} & string)): void;
+    /**
+     * Removes a specific property override.
+     *
+     * @param name The property name to remove the override for
+     *
+     * @deprecated The name is missing an `r`. Use {@link removeOverride} instead — this
+     * alias is kept so existing code keeps working and will be removed in a future version.
+     */
     removeOveride<K extends NonFunctionPropertyNames<T>>(name: K | ({} & string)): void;
     /**
      * Removes all property overrides from this block.
@@ -11491,7 +11537,7 @@ export declare class MaterialPropertyBlock<T extends Material = Material> {
      * });
      * ```
      *
-     * @see {@link removeOveride} - To remove a single override
+     * @see {@link removeOverride} - To remove a single override
      * @see {@link dispose} - To completely remove the property block and clean up resources
      */
     clearAllOverrides(): void;
@@ -11608,6 +11654,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)
@@ -13333,7 +13392,7 @@ export declare class NestedGltf extends Component {
     private hash;
 }
 
-declare enum NEToneMappingMode {
+export declare enum NEToneMappingMode {
     None = 0,
     Neutral = 1,// Neutral tonemapper, close to Reinhard
     ACES = 2,// ACES Filmic reference tonemapper (custom approximation)
@@ -14039,6 +14098,8 @@ export declare function offXRSessionEnd(fn: (evt: XRSessionEventArgs) => void):
  */
 export declare function offXRSessionStart(fn: (evt: XRSessionEventArgs) => void): void;
 
+/* Excluded from this release type: oMxKl */
+
 /**
  * @experimental
  * Subscribe to a DOM event on any {@link EventTarget} (window, document, HTML elements, etc.)
@@ -16258,6 +16319,24 @@ export declare class OrbitControls extends Component implements ICameraControlle
          get effects(): readonly IPostProcessingEffect[];
          get dirty(): boolean;
          set dirty(value: boolean);
+         private _enabled;
+         /**
+          * Whether the postprocessing stack runs at all. When disabled the scene is
+          * rendered directly, with no effects and no composer.
+          *
+          * Every effect keeps its own `enabled` state, so switching this back on
+          * restores exactly the stack that was there before. Useful for a quality
+          * setting, for a clean screenshot, or for comparing a scene with and
+          * without effects.
+          *
+          * @default true
+          * @example
+          * ```ts
+          * context.postprocessing.enabled = false;
+          * ```
+          */
+         get enabled(): boolean;
+         set enabled(value: boolean);
          /** The internal PostProcessingHandler that manages the EffectComposer pipeline */
          get handler(): IPostProcessingHandler | null;
          /**
@@ -16728,6 +16807,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      export { QTrailParticle }
 
+     export declare enum QualityLevel {
+         LOW = 0,
+         MEDIUM = 1,
+         HIGH = 2,
+         ULTRA = 3
+     }
+
      declare type Quat = {
          x: number;
          y: number;
@@ -18907,7 +18993,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**See (N8AO documentation)[https://github.com/N8python/n8ao] */
-     declare enum ScreenSpaceAmbientOcclusionN8QualityMode {
+     export declare enum ScreenSpaceAmbientOcclusionN8QualityMode {
          Performance = 0,
          Low = 1,
          Medium = 2,
@@ -25112,6 +25198,32 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      export declare type XRGestureName = "pinch";
 
+     /**
+      * Renders a skinned hand mesh and drives its bones from the tracked WebXR joint poses.
+      *
+      * @see {@link XRControllerModel} which creates one per tracked hand.
+      */
+     declare 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, onLoad?: ((object: Object3D) => void) | null);
+         /** Copies the current tracked joint poses onto the mesh bones. Called every XR frame. */
+         updateMesh(): void;
+     }
+
      declare type XRMesh_2 = {
          meshSpace: XRSpace;
          lastChangedTime: number;