@needle-tools/engine 4.13.1 → 4.14.0-next.31f837e

package/dist/needle-engine.d.ts

@@ -4684,6 +4684,7 @@ export declare function createMotion(name: string, id?: InstantiateIdProvider):
  *
  * @summary Makes objects follow the cursor/touch position in 3D space
  * @category Interactivity
+ * @category Web
  * @group Components
  * @component
  */
@@ -5081,6 +5082,7 @@ declare enum DeviceType {
 
 /**
  * Utility functions to detect certain device types (mobile, desktop), browsers, or capabilities.
+ * @category Utilities
  */
 export declare namespace DeviceUtilities {
     /** @returns `true` for MacOS or Windows devices. `false` for Hololens and other headsets. */
@@ -10054,6 +10056,40 @@ export declare class MaskableGraphic extends Graphic {
     protected onAfterCreated(): void;
 }
 
+export declare class MaterialPropertyBlock<T extends Material = Material> {
+    private _overrides;
+    private _defines;
+    private _object;
+    get object(): Object3D | null;
+    constructor(object?: Object3D | null);
+    static get<T extends Material = Material>(object: Object3D): MaterialPropertyBlock<T>;
+    dispose(): void;
+    setOverride<K extends NonFunctionPropertyNames<T>>(name: K, value: T[K], textureTransform?: TextureTransform): void;
+    setOverride(name: string, value: MaterialPropertyType, textureTransform?: TextureTransform): void;
+    getOverride(name: string): PropertyBlockOverride | undefined;
+    clearOverride(name: string): void;
+    clearAllOverrides(): void;
+    removeOverride(name: string): void;
+    get overrides(): PropertyBlockOverride[];
+    hasOverrides(): boolean;
+    /**
+     * Set a shader define that will be included in the program cache key
+     * This allows different objects sharing the same material to have different shader programs
+     */
+    setDefine(name: string, value: string | number | boolean): void;
+    /**
+     * Remove a shader define
+     */
+    clearDefine(name: string): void;
+    /**
+     * Get all defines set on this property block
+     */
+    getDefines(): Readonly<Record<string, string | number | boolean>>;
+    getCacheKey(): string;
+}
+
+declare type MaterialPropertyType = number | number[] | Color | Texture | Vector2 | Vector3 | Vector4 | null;
+
 export declare namespace MaterialX {
     /**
      * Utility function to load a MaterialX material from a URL. This can be used in your own code to load MaterialX materials outside of the glTF loading process. The URL should point to a MaterialX XML file.
@@ -11319,7 +11355,12 @@ export declare type NeedleXRHitTestResult = {
  * The XRRig can be accessed via the `rig` property
  * Set a custom XRRig via `NeedleXRSession.addRig(...)` or `NeedleXRSession.removeRig(...)`
  * By default the active XRRig with the highest priority in the scene is used
+ *
+ * ### Screenshots in XR
+ * Screenshots work automatically during XR sessions, including AR camera feed compositing. See {@link screenshot2} for more information.
+ *
  * @category XR
+ * @see {@link screenshot2} for taking screenshots in XR sessions
  */
 export declare class NeedleXRSession implements INeedleXRSession {
     private static _sync;
@@ -12177,6 +12218,10 @@ export declare class NoiseModule {
     apply(_index: number, pos: Vec3, vel: Vec3, _deltaTime: number, age: number, life: number): void;
 }
 
+declare type NonFunctionPropertyNames<T> = {
+    [K in keyof T]: T[K] extends Function ? never : K;
+}[keyof T];
+
 /** Removes all undefined functions */
 declare type NoUndefinedNoFunctions<T> = FilterTypes<T, Function | undefined | null>;
 
@@ -12592,6 +12637,7 @@ export declare function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void):
  * OpenURL behaviour opens a URL in a new tab or window when the object (or any if it's children) is clicked.
  *
  * @category Interactivity
+ * @category Web
  * @group Components
  */
 export declare class OpenURL extends Component implements IPointerClickHandler {
@@ -14645,6 +14691,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
          constructor(reason: string);
      }
 
+     declare interface PropertyBlockOverride {
+         name: string;
+         value: MaterialPropertyType;
+         textureTransform?: TextureTransform;
+     }
+
      export declare const PUBLIC_KEY: string;
 
      /** Adds an entry to the browser history. Internally uses `window.history.pushState` */
@@ -15075,7 +15127,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
          awake(): void;
          start(): void;
          onDestroy(): void;
-         private static _rendererMaterialsCache;
          onSet(_rend: IRenderer): void;
          onUnset(_rend: IRenderer): void;
      }
@@ -15477,23 +15528,27 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private lightmapIndex;
          private lightmapScaleOffset;
          private readonly renderer;
-         private readonly clonedMaterials;
+         private _isApplied;
          private get context();
          private get gameObject();
          private lightmapTexture;
-         private lightmapScaleOffsetUniform;
-         private lightmapUniform;
          constructor(renderer: Renderer);
          init(lightmapIndex: number, lightmapScaleOffset: Vector4, lightmapTexture: Texture): void;
-         updateLightmapUniforms(material: Material): void;
+         updateLightmapUniforms(_material: any): void;
          /**
-          * Apply the lightmap to the object. This will clone the material and set the lightmap texture and scale/offset
+          * Apply the lightmap to the object using MaterialPropertyBlock instead of cloning materials.
+          * The lightmap texture and its per-object UV transform are set as overrides via PropertyBlock.
+          * Three.js reads material.lightMap to determine shader defines and upload uniforms,
+          * and uses texture.offset/repeat to compute lightMapTransform in the vertex shader.
           */
          applyLightmap(): void;
+         /** Update the lightMap override on all property blocks (e.g. after LOD swap) */
+         private updatePropertyBlockTexture;
+         /**
+          * Remove the lightmap from the object
+          */
+         onUnset(): void;
          private ensureLightmapUvs;
-         private ensureLightmapMaterial;
-         private assignLightmapTexture;
-         private onBeforeCompile;
          private setLightmapDebugMaterial;
      }
 
@@ -16327,40 +16382,179 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * const dataUrl = screenshot();
       * saveImage(dataUrl, "screenshot.png");
       * ```
+      *
       */
      export declare function screenshot(context?: Context, width?: number, height?: number, mimeType?: ScreenshotImageMimeType, camera?: Camera_2 | null): string | null;
 
      /**
-      * Take a screenshot from the current scene and return a {@link Texture}. This can applied to a surface in 3D space.
+      * Take a screenshot from the current scene and return a {@link Texture}. This can be applied to a surface in 3D space.
       * @param opts Provide `{ type: "texture" }` to get a texture instead of a data url.
       * @returns The texture of the screenshot. Returns null if the screenshot could not be taken.
+      * @category Utilities
+      * @example
+      * ```ts
+      * // Create a texture from the current view
+      * const screenshotTexture = screenshot2({ type: "texture", width: 512, height: 512 });
+      * if (screenshotTexture) {
+      *   myMaterial.map = screenshotTexture;
+      *   myMaterial.needsUpdate = true;
+      * }
+      *
+      * // Update an existing texture
+      * const existingTexture = new Texture();
+      * screenshot2({ type: "texture", target: existingTexture, transparent: true });
+      * ```
       */
      export declare function screenshot2(opts: ScreenshotOptionsTexture): Texture | null;
 
      /**
-      * Take a screenshot from the current scene.
-      * @param opts
-      * @returns The data url of the screenshot. Returns null if the screenshot could not be taken.
+      * Take a screenshot from the current scene and return a data URL string.
+      *
+      * @param opts Screenshot options. All properties are optional.
+      * @returns The data URL of the screenshot (e.g., "data:image/png;base64,..."). Returns null if the screenshot could not be taken.
+      * @category Utilities
+      *
+      * @example Basic screenshot
       * ```ts
-      * const res = screenshot2({
-      *    width: 1024,
+      * // Take a simple screenshot with default settings
+      * const dataUrl = screenshot2({});
+      * console.log(dataUrl); // "data:image/webp;base64,..."
+      * ```
+      *
+      * @example High-resolution screenshot with transparent background
+      * ```ts
+      * const dataUrl = screenshot2({
+      *   width: 2048,
+      *   height: 2048,
+      *   mimeType: "image/png",
+      *   transparent: true,
+      *   trim: true, // Remove transparent edges
+      * });
+      * ```
+      *
+      * @example Screenshot with custom background color
+      * ```ts
+      * import { Color } from "three";
+      *
+      * const dataUrl = screenshot2({
+      *   width: 1024,
       *   height: 1024,
-      *  mimeType: "image/webp",
-      * transparent: true,
-      * })
-      * // use saveImage to download the image
-      * saveImage(res, "screenshot.webp");
+      *   background: new Color(0x00ff00), // Green background
+      * });
+      * ```
+      *
+      * @example Download screenshot automatically
+      * ```ts
+      * screenshot2({
+      *   width: 1920,
+      *   height: 1080,
+      *   mimeType: "image/jpeg",
+      *   download_filename: "my-scene.jpg",
+      * });
+      * ```
+      *
+      * @example Manual download using saveImage
+      * ```ts
+      * const dataUrl = screenshot2({
+      *   width: 1024,
+      *   height: 1024,
+      *   mimeType: "image/webp",
+      *   transparent: true,
+      * });
+      * if (dataUrl) {
+      *   saveImage(dataUrl, "screenshot.webp");
+      * }
+      * ```
+      *
+      * @example Screenshot from specific camera
+      * ```ts
+      * const myCamera = this.gameObject.getComponent(Camera);
+      * const dataUrl = screenshot2({
+      *   camera: myCamera,
+      *   width: 1024,
+      *   height: 1024,
+      * });
       * ```
       */
      export declare function screenshot2(opts: ScreenshotOptionsDataUrl): string | null;
 
      /**
-      * Take a screenshot asynchronously from the current scene.
-      * @returns A promise that resolves with the blob of the screenshot. Returns null if the screenshot could not be taken.
-      * @param {ScreenshotOptionsBlob} opts Set `{ type: "blob" }` to get a blob instead of a data url.
+      * Take a screenshot asynchronously and return a Blob. This is useful when you need to process or upload the image data.
+      *
+      * @param opts Set `{ type: "blob" }` to get a blob instead of a data url. All other {@link ScreenshotOptions} are also available.
+      * @returns A Promise that resolves with the Blob of the screenshot. Returns null if the screenshot could not be taken.
+      * @category Utilities
+      *
+      * @example Upload screenshot to server
+      * ```ts
+      * const blob = await screenshot2({ type: "blob", mimeType: "image/png" });
+      * if (blob) {
+      *   const formData = new FormData();
+      *   formData.append("screenshot", blob, "screenshot.png");
+      *   await fetch("/api/upload", { method: "POST", body: formData });
+      * }
+      * ```
+      *
+      * @example Save blob to file (browser download)
+      * ```ts
+      * const blob = await screenshot2({
+      *   type: "blob",
+      *   width: 1920,
+      *   height: 1080,
+      *   transparent: true
+      * });
+      * if (blob) {
+      *   const url = URL.createObjectURL(blob);
+      *   saveImage(url, "screenshot.png");
+      *   URL.revokeObjectURL(url); // Clean up
+      * }
+      * ```
       */
      export declare function screenshot2(opts: ScreenshotOptionsBlob): Promise<Blob | null>;
 
+     /**
+      * Take a screenshot and share it using the Web Share API (mobile-friendly).
+      *
+      * **Note**: The Web Share API is only available in secure contexts (HTTPS) and may not be supported on all platforms/browsers.
+      *
+      * @param opts Set `{ type: "share" }` to share the screenshot. Additional options like `filename`, `title`, `text`, and `url` can be provided.
+      * @returns A Promise that resolves with an object containing the blob and whether it was successfully shared.
+      * @category Utilities
+      *
+      * @example Share screenshot on mobile
+      * ```ts
+      * const result = await screenshot2({
+      *   type: "share",
+      *   filename: "my-creation.png",
+      *   title: "Check out my 3D scene!",
+      *   text: "I created this with Needle Engine",
+      *   url: "https://engine.needle.tools",
+      *   mimeType: "image/png",
+      * });
+      *
+      * if (result.shared) {
+      *   console.log("Screenshot shared successfully!");
+      * } else {
+      *   console.log("User cancelled or sharing not supported");
+      * }
+      * ```
+      *
+      * @example Share with fallback
+      * ```ts
+      * const result = await screenshot2({
+      *   type: "share",
+      *   filename: "screenshot.webp",
+      *   file_type: "image/webp",
+      * });
+      *
+      * if (!result.shared && result.blob) {
+      *   // Fallback: download the image instead
+      *   const url = URL.createObjectURL(result.blob);
+      *   saveImage(url, "screenshot.webp");
+      *   URL.revokeObjectURL(url);
+      * }
+      * ```
+      */
      export declare function screenshot2(opts: ScreenshotOptionsShare): Promise<ScreenshotOptionsShareReturnType>;
 
      declare type ScreenshotImageMimeType = "image/webp" | "image/png" | "image/jpeg";
@@ -16422,11 +16616,29 @@ export declare class OrbitControls extends Component implements ICameraControlle
      };
 
      export declare type ScreenshotOptionsShare = ScreenshotOptions & {
+         /**
+          * Set `{ type: "share" }` to share the screenshot using the Web Share API. The promise will resolve with the blob of the screenshot and whether it was shared successfully or not. Note that the Web Share API is only available in secure contexts (HTTPS) and on some platforms.
+          */
          type: "share";
+         /**
+          * The filename to use when sharing the screenshot. If not provided, a default filename will be used.
+          */
          filename?: string;
+         /**
+          * The mime type of the shared file. If not provided, the mime type will be inferred from the screenshot options or default to "image/png".
+          */
          file_type?: ScreenshotImageMimeType;
+         /**
+          * The title to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+          */
          title?: string;
+         /**
+          * The text to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+          */
          text?: string;
+         /**
+          * The URL to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+          */
          url?: string;
      };
 
@@ -16568,6 +16780,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *
       * @summary Links scroll position to target objects
       * @category Web
+      * @category Interaction
       * @group Components
       * @component
       */
@@ -19105,6 +19318,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /**@obsolete use Graphics.textureToCanvas */
      export declare function textureToCanvas(texture: Texture, force?: boolean): HTMLCanvasElement | null;
 
+     declare interface TextureTransform {
+         offset?: Vector2;
+         repeat?: Vector2;
+     }
+
      declare enum TextWrapMode {
          singleLine = "singleLine",
          hardBreaks = "hardBreaks",
@@ -20779,11 +20997,20 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /**
       * WebARCameraBackground is a component that allows to display the camera feed as a background in an AR session to more easily blend the real world with the virtual world or applying effects to the camera feed.
       *
+      * This component automatically requests `camera-access` permission when entering AR mode, which is required to:
+      * - Display the real-world camera feed as a background
+      * - Include the camera feed in AR screenshots taken with {@link screenshot2}
+      *
+      * **Note**: If you want to take AR screenshots with the camera feed but don't need to display it as a background,
+      * you can still add this component to your scene (it will request camera access) or manually request the
+      * `camera-access` feature in your `onBeforeXR` method.
+      *
       * - Example: https://samples.needle.tools/ar-camera-background
       *
       * @summary Displays the camera feed as background in WebAR sessions
       * @category XR
       * @group Components
+      * @see {@link screenshot2} for taking screenshots in AR (requires camera access for camera feed compositing)
       */
      export declare class WebARCameraBackground extends Component {
          /* Excluded from this release type: onBeforeXR */
@@ -20942,6 +21169,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @see {@link XRControllerMovement} for VR locomotion
       * @see {@link WebARSessionRoot} for AR session configuration
       * @see {@link Avatar} for networked user avatars
+      * @see {@link screenshot2} for taking screenshots in XR (including AR camera feed compositing)
       * @link https://engine.needle.tools/docs/xr.html
       * @link https://engine.needle.tools/samples/?overlay=samples&tag=xr
       * @link https://engine.needle.tools/samples/collaborative-sandbox