@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
131 lines (130 loc) • 5.86 kB
TypeScript
import { Object3D } from "three";
import { Behaviour } from "../../Component.js";
import type { IUSDExporterExtension } from "./Extension.js";
/**
* Custom branding for the QuickLook overlay, used by {@link USDZExporter}.
*/
export declare class CustomBranding {
/** The call to action button text. If not set, the button will close the QuickLook overlay. */
callToAction?: string;
/** The title of the overlay. */
checkoutTitle?: string;
/** The subtitle of the overlay. */
checkoutSubtitle?: string;
/** if assigned the call to action button in quicklook will open the URL. Otherwise it will just close quicklook. */
callToActionURL?: string;
}
/**
* Exports the current scene or a specific object as USDZ file and opens it in QuickLook on iOS/iPadOS/visionOS.
* The USDZ file is generated using the Needle Engine ThreeUSDZExporter.
* The exporter supports various extensions to add custom behaviors and interactions to the USDZ file.
* The exporter can automatically collect Animations and AudioSources and export them as playing at the start.
* The exporter can also add a custom QuickLook overlay with a call to action button and custom branding.
* @example
* ```typescript
* const usdz = new USDZExporter();
* usdz.objectToExport = myObject;
* usdz.autoExportAnimations = true;
* usdz.autoExportAudioSources = true;
* usdz.exportAsync();
* ```
* @category XR
* @group Components
*/
export declare class USDZExporter extends Behaviour {
/**
* Assign the object to export as USDZ file. If undefined or null, the whole scene will be exported.
*/
objectToExport: Object3D | null | undefined;
/** Collect all Animations/Animators automatically on export and emit them as playing at the start.
* Animator state chains and loops will automatically be collected and exported in order as well.
* If this setting is off, Animators need to be registered by components – for example from PlayAnimationOnClick.
*/
autoExportAnimations: boolean;
/** Collect all AudioSources automatically on export and emit them as playing at the start.
* They will loop according to their settings.
* If this setting is off, Audio Sources need to be registered by components – for example from PlayAudioOnClick.
*/
autoExportAudioSources: boolean;
exportFileName: string | null | undefined;
customUsdzFile: string | null | undefined;
customBranding?: CustomBranding;
anchoringType: "plane" | "image" | "face" | "none";
maxTextureSize: 256 | 512 | 1024 | 2048 | 4096 | 8192;
planeAnchoringAlignment: "horizontal" | "vertical" | "any";
/** Enabling this option will export QuickLook-specific preliminary behaviours along with the USDZ files.
* These extensions are only supported on QuickLook on iOS/visionOS/MacOS.
* Keep this option off for general USDZ usage.
*/
interactive: boolean;
/** Enabling this option will export the USDZ file with RealityKit physics components.
* Rigidbody and Collider components will be converted to their RealityKit counterparts.
* Physics are supported on QuickLook in iOS 18+ and VisionOS 1+.
* Physics export is automatically turned off when there are no Rigidbody components anywhere on the exported object.
*/
physics: boolean;
allowCreateQuicklookButton: boolean;
quickLookCompatible: boolean;
/**
* Extensions to add custom behaviors and interactions to the USDZ file.
* You can add your own extensions here by extending {@link IUSDExporterExtension}.
*/
extensions: IUSDExporterExtension[];
private link;
private button?;
/** @internal */
start(): void;
/** @internal */
onEnable(): void;
/** @internal */
onDisable(): void;
private onClickedOpenInARElement;
/**
* Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
* Use the various public properties of USDZExporter to customize export behaviour.
* @deprecated use {@link exportAndOpen} instead
*/
exportAsync(): Promise<Blob | null>;
/**
* Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
* @returns a Promise<Blob> containing the USDZ file
*/
exportAndOpen(): Promise<Blob | null>;
/**
* Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
* @returns a Promise<Blob> containing the USDZ file
*/
export(objectToExport: Object3D | undefined): Promise<Blob | null>;
private readonly _currentExportTasks;
private _previousTimeScale;
private internalExport;
/**
* Opens QuickLook on iOS/iPadOS/visionOS with the given content in AR mode.
* @param content The URL to the .usdz or .reality file or a blob containing an USDZ file.
* @param name Download filename
*/
openInQuickLook(content: Blob | string, name: string): void;
/**
* Downloads the given blob as a file.
*/
download(blob: Blob, name: string): void;
private static save;
private lastCallback?;
private quicklookCallback;
private buildQuicklookOverlay;
private static invertForwardMatrix;
private static invertForwardQuaternion;
private _rootSessionRootWasAppliedTo;
private _rootPositionBeforeExport;
private _rootRotationBeforeExport;
private _rootScaleBeforeExport;
getARScaleAndTarget(): {
scale: number;
_invertForward: boolean;
target: Object3D;
sessionRoot: Object3D | null;
};
private applyWebARSessionRoot;
private revertWebARSessionRoot;
private createQuicklookButton;
}