@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.
256 lines (255 loc) • 11.3 kB
TypeScript
import { Context } from "../engine_setup.js";
import { type INeedleEngineComponent, type LoadedModel } from "../engine_types.js";
declare global {
interface HTMLElementTagNameMap {
"needle-engine": NeedleEngineWebComponent;
}
}
type TonemappingAttributeOptions = "none" | "linear" | "neutral" | "agx";
/** Supported attributes for the `<needle-engine>` web component. */
export interface NeedleEngineAttributes {
/** Change which model gets loaded. */
'src': string;
/** String attached to the context for caching/identification. */
'hash': string;
/** Set to automatically add OrbitControls to the loaded scene. */
'camera-controls': string;
/** Override the default draco decoder path location. */
'dracoDecoderPath': string;
/** Override the default draco library type. */
'dracoDecoderType': 'wasm' | 'js';
/** Override the default KTX2 transcoder/decoder path. */
'ktx2DecoderPath': string;
/** Prevent context from being disposed when element is removed from DOM. */
'keep-alive': 'true' | 'false';
/** Loading overlay style. */
'loading-style': 'dark' | 'light' | 'auto';
/** URL to .exr, .hdr, .png, .jpg to be used as skybox. */
'background-image': string;
/** Rotation of the background image in degrees. */
'background-rotation': string | number;
/** URL to .exr, .hdr, .png, .jpg to be used for lighting. */
'environment-image': string;
/** Intensity multiplier for environment lighting. */
'environment-intensity': string;
/** Blurs the background image. 0 (sharp) to 1 (fully blurred). */
'background-blurriness': string;
/** Intensity multiplier for the background image. */
'background-intensity': string;
/** CSS background color if no skybox/background image is provided. */
'background-color': string;
/** Enable/disable renderer canvas transparency. */
'transparent': 'true' | 'false';
/** Enable/disable contact shadows. */
'contact-shadows': 'true' | 'false';
/** Tonemapping mode. */
'tone-mapping': TonemappingAttributeOptions;
/** Exposure multiplier for tonemapping. */
'tone-mapping-exposure': string;
/** CSS selector or HTMLElement for camera focus. */
'focus-rect': string | HTMLElement;
/** Allow pointer events to pass through transparent parts. */
'clickthrough': 'true' | 'false';
/** Automatically fit model into camera view on load. */
'auto-fit': 'true' | 'false';
/** Auto-rotate model until user interacts. */
'auto-rotate': 'true' | 'false';
/** Play animations automatically on scene load. */
'autoplay': 'true' | 'false';
}
/**
* The `<needle-engine>` web component. See {@link NeedleEngineAttributes} attributes for supported attributes
* The web component creates and manages a Needle Engine context, which is responsible for rendering a 3D scene using threejs.
* The context is created when the `src` attribute is set, and disposed when the element is removed from the DOM. You can prevent cleanup by setting the `keep-alive` attribute to `true`.
* The context is accessible from the `<needle-engine>` element: `document.querySelector("needle-engine").context`.
* See {@link https://engine.needle.tools/docs/reference/needle-engine-attributes}
*
* @example Basic usage
* ```html
* <needle-engine src="https://example.com/scene.glb"></needle-engine>
* ```
*
* @example With camera controls disabled
* ```html
* <needle-engine src="https://example.com/scene.glb" camera-controls="false"></needle-engine>
* ```
*
* @see {@link NeedleButtonElement} for adding AR/VR/Quicklook buttons via <needle-button>
* @see {@link NeedleMenu} for the built-in menu configuration component
*/
export declare class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
static get observedAttributes(): string[];
get loadingProgress01(): number;
get loadingFinished(): boolean;
/**
* If set to false the camera controls are disabled. Default is true.
* @type {boolean | null}
* @memberof NeedleEngineAttributes
* @example
* <needle-engine camera-controls="false"></needle-engine>
* @example
* <needle-engine camera-controls="true"></needle-engine>
* @example
* <needle-engine camera-controls></needle-engine>
* @example
* <needle-engine></needle-engine>
* @returns {boolean | null} if the attribute is not set it returns null
*/
get cameraControls(): boolean | null;
set cameraControls(value: boolean | null);
/**
* Get the current context for this web component instance. The context is created when the src attribute is set and the loading has finished.
* The context is disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).
* @returns a promise that resolves to the context when the loading has finished
*/
getContext(): Promise<Context>;
/**
* Get the context that is created when the src attribute is set and the loading has finished.
*/
get context(): Context | undefined;
private _context?;
private _overlay_ar;
private _loadingProgress01;
private _loadingView?;
private _previousSrc;
/** @private set to true after <needle-engine> did load completely at least once. Set to false when < to false when <needle-engine> is removed from the document removed from the document */
private _didFullyLoad;
private _didInitialize;
constructor();
private ensureInitialized;
private initializeDom;
/**
* @internal
*/
connectedCallback(): void;
/**
* @internal
*/
disconnectedCallback(): void;
connectedMoveCallback(): void;
/**
* @internal
*/
attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
/** The tonemapping setting configured as an attribute on the <needle-engine> component */
get toneMapping(): TonemappingAttributeOptions | null | undefined;
private _loadId;
private _abortController;
private _lastSourceFiles;
private _createContextPromise;
/**
* Check if we have a context. If not a new one is created.
*/
private getOrCreateContext;
private onLoad;
private applyAttributes;
private onXRSessionStarted;
/** called by the context when the first frame has been rendered */
private onReady;
private onError;
private getSourceFiles;
private checkIfSourceHasChanged;
private _previouslyRegisteredMap;
private ensureLoadStartIsRegistered;
private registerEventFromAttribute;
private setPublicKey;
private setVersion;
/**
* @internal
*/
getAROverlayContainer(): HTMLElement;
/**
* @internal
*/
getVROverlayContainer(): HTMLElement | null;
/**
* @internal
*/
onEnterAR(session: XRSession): void;
/**
* @internal
*/
onExitAR(session: XRSession): void;
/**
* @internal
*/
onEnterVR(session: XRSession): void;
/**
* @internal
*/
onExitVR(session: XRSession): void;
private onSetupAR;
private onSetupVR;
private onSetupDesktop;
private setupElementsForMode;
private foreachHtmlElement;
private onBeforeBeginLoading;
/** Set a known Needle Engine attribute. See {@link NeedleEngineAttributes} for available attributes. */
setAttribute<K extends keyof NeedleEngineAttributes>(name: K, value: NeedleEngineAttributes[K]): void;
setAttribute(qualifiedName: string, value: string): void;
/** Get a known Needle Engine attribute. See {@link NeedleEngineAttributes} for available attributes. */
getAttribute<K extends keyof NeedleEngineAttributes>(qualifiedName: K): string | null;
getAttribute(qualifiedName: string): string | null;
/**
* Emitted when loading begins for the scene. The event is cancelable — calling `preventDefault()`
* will stop the default loading UI behavior, so apps can implement custom loading flows.
*/
addEventListener(type: 'loadstart', listener: (ev: CustomEvent<{
context: Context;
alias: string | null;
}>) => void, options?: boolean | AddEventListenerOptions): void;
/** Emitted repeatedly while loading resources. Use the event detail to show progress. */
addEventListener(type: 'progress', listener: (ev: CustomEvent<{
context: Context;
name: string;
progress: ProgressEvent<EventTarget>;
index: number;
count: number;
totalProgress01: number;
}>) => void, options?: boolean | AddEventListenerOptions): void;
/** Emitted when scene loading has finished. */
addEventListener(type: 'loadfinished', listener: (ev: CustomEvent<{
context: Context;
src: string | null;
loadedFiles: LoadedModel[];
}>) => void, options?: boolean | AddEventListenerOptions): void;
/** Emitted when an XR session ends. */
addEventListener(type: 'xr-session-ended', listener: (ev: CustomEvent<{
session: XRSession | null;
context: Context;
sessionMode: XRSessionMode | undefined;
}>) => void, options?: boolean | AddEventListenerOptions): void;
/** Emitted when entering an AR session. */
addEventListener(type: 'enter-ar', listener: (ev: CustomEvent<{
session: XRSession;
context: Context;
htmlContainer: HTMLElement | null;
}>) => void, options?: boolean | AddEventListenerOptions): void;
/** Emitted when exiting an AR session. */
addEventListener(type: 'exit-ar', listener: (ev: CustomEvent<{
session: XRSession;
context: Context;
htmlContainer: HTMLElement | null;
}>) => void, options?: boolean | AddEventListenerOptions): void;
/** Emitted when entering a VR session. */
addEventListener(type: 'enter-vr', listener: (ev: CustomEvent<{
session: XRSession;
context: Context;
}>) => void, options?: boolean | AddEventListenerOptions): void;
/** Emitted when exiting a VR session. */
addEventListener(type: 'exit-vr', listener: (ev: CustomEvent<{
session: XRSession;
context: Context;
}>) => void, options?: boolean | AddEventListenerOptions): void;
/** Emitted when the engine has rendered its first frame and is ready. */
addEventListener(type: 'ready', listener: (ev: Event) => void, options?: boolean | AddEventListenerOptions): void;
/** Emitted when an XR session is started. You can do additional setup here. */
addEventListener(type: 'xr-session-started', listener: (ev: CustomEvent<{
session: XRSession;
context: Context;
}>) => void, options?: boolean | AddEventListenerOptions): void;
addEventListener<K extends keyof HTMLElementEventMap>(type: ({} & K), listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
}
export {};