Class NeedleEngineWebComponent

The <needle-engine> web component. See 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 https://engine.needle.tools/docs/reference/needle-engine-attributes

Example

<needle-engine src="https://example.com/scene.glb"></needle-engine>

Example

<needle-engine src="https://example.com/scene.glb" camera-controls="false"></needle-engine>

Hierarchy

Implements

Constructors

constructor

Accessors

cameraControls context loadingFinished loadingProgress01 toneMapping observedAttributes

Methods

addEventListener connectedMoveCallback getContext

Constructors

constructor

Accessors

cameraControls

  • get cameraControls(): null | boolean

    If set to false the camera controls are disabled. Default is true.

    Returns null | boolean

    if the attribute is not set it returns 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>
  • set cameraControls(value: null | boolean): void

    Parameters

    • value: null | boolean

    Returns void

context

  • get context(): Context

    Get the context that is created when the src attribute is set and the loading has finished.

    Returns Context

loadingFinished

  • get loadingFinished(): boolean

    Returns boolean

loadingProgress01

  • get loadingProgress01(): number

    Returns number

toneMapping

  • get toneMapping(): undefined | null | TonemappingAttributeOptions

    The tonemapping setting configured as an attribute on the component

    Returns undefined | null | TonemappingAttributeOptions

StaticobservedAttributes

  • get observedAttributes(): string[]

    Returns string[]

Methods

addEventListener

  • addEventListener(
        type: "loadstart",
        listener: (
            ev: CustomEvent<{ alias: null | string; context: Context }>,
        ) => void,
        options?: boolean | AddEventListenerOptions,
    ): void

    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.

    Parameters

    • type: "loadstart"
    • listener: (ev: CustomEvent<{ alias: null | string; context: Context }>) => void
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener(
        type: "progress",
        listener: (
            ev: CustomEvent<
                {
                    context: Context;
                    count: number;
                    index: number;
                    name: string;
                    progress: ProgressEvent<EventTarget>;
                    totalProgress01: number;
                },
            >,
        ) => void,
        options?: boolean | AddEventListenerOptions,
    ): void

    Emitted repeatedly while loading resources. Use the event detail to show progress.

    Parameters

    • type: "progress"
    • listener: (
          ev: CustomEvent<
              {
                  context: Context;
                  count: number;
                  index: number;
                  name: string;
                  progress: ProgressEvent<EventTarget>;
                  totalProgress01: number;
              },
          >,
      ) => void
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener(
        type: "loadfinished",
        listener: (
            ev: CustomEvent<
                { context: Context; loadedFiles: LoadedModel[]; src: null
                | string },
            >,
        ) => void,
        options?: boolean | AddEventListenerOptions,
    ): void

    Emitted when scene loading has finished.

    Parameters

    • type: "loadfinished"
    • listener: (
          ev: CustomEvent<
              { context: Context; loadedFiles: LoadedModel[]; src: null
              | string },
          >,
      ) => void
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener(
        type: "xr-session-ended",
        listener: (
            ev: CustomEvent<
                {
                    context: Context;
                    session: null
                    | XRSession;
                    sessionMode: undefined | XRSessionMode;
                },
            >,
        ) => void,
        options?: boolean | AddEventListenerOptions,
    ): void

    Emitted when an XR session ends.

    Parameters

    • type: "xr-session-ended"
    • listener: (
          ev: CustomEvent<
              {
                  context: Context;
                  session: null
                  | XRSession;
                  sessionMode: undefined | XRSessionMode;
              },
          >,
      ) => void
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener(
        type: "enter-ar",
        listener: (
            ev: CustomEvent<
                {
                    context: Context;
                    htmlContainer: null
                    | HTMLElement;
                    session: XRSession;
                },
            >,
        ) => void,
        options?: boolean | AddEventListenerOptions,
    ): void

    Emitted when entering an AR session.

    Parameters

    • type: "enter-ar"
    • listener: (
          ev: CustomEvent<
              {
                  context: Context;
                  htmlContainer: null
                  | HTMLElement;
                  session: XRSession;
              },
          >,
      ) => void
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener(
        type: "exit-ar",
        listener: (
            ev: CustomEvent<
                {
                    context: Context;
                    htmlContainer: null
                    | HTMLElement;
                    session: XRSession;
                },
            >,
        ) => void,
        options?: boolean | AddEventListenerOptions,
    ): void

    Emitted when exiting an AR session.

    Parameters

    • type: "exit-ar"
    • listener: (
          ev: CustomEvent<
              {
                  context: Context;
                  htmlContainer: null
                  | HTMLElement;
                  session: XRSession;
              },
          >,
      ) => void
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener(
        type: "enter-vr",
        listener: (
            ev: CustomEvent<{ context: Context; session: XRSession }>,
        ) => void,
        options?: boolean | AddEventListenerOptions,
    ): void

    Emitted when entering a VR session.

    Parameters

    • type: "enter-vr"
    • listener: (ev: CustomEvent<{ context: Context; session: XRSession }>) => void
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener(
        type: "exit-vr",
        listener: (
            ev: CustomEvent<{ context: Context; session: XRSession }>,
        ) => void,
        options?: boolean | AddEventListenerOptions,
    ): void

    Emitted when exiting a VR session.

    Parameters

    • type: "exit-vr"
    • listener: (ev: CustomEvent<{ context: Context; session: XRSession }>) => void
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener(
        type: "ready",
        listener: (ev: Event) => void,
        options?: boolean | AddEventListenerOptions,
    ): void

    Emitted when the engine has rendered its first frame and is ready.

    Parameters

    • type: "ready"
    • listener: (ev: Event) => void
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener(
        type: "xr-session-started",
        listener: (
            ev: CustomEvent<{ context: Context; session: XRSession }>,
        ) => void,
        options?: boolean | AddEventListenerOptions,
    ): void

    Emitted when an XR session is started. You can do additional setup here.

    Parameters

    • type: "xr-session-started"
    • listener: (ev: CustomEvent<{ context: Context; session: XRSession }>) => void
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener<K extends keyof HTMLElementEventMap>(
        type: K,
        listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown,
        options?: boolean | AddEventListenerOptions,
    ): void

    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.

    Type Parameters

    • K extends keyof HTMLElementEventMap

    Parameters

    • type: K
    • listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener<K extends keyof HTMLElementEventMap>(
        type: K,
        listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any,
        options?: boolean | AddEventListenerOptions,
    ): void

    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.

    Type Parameters

    • K extends keyof HTMLElementEventMap

    Parameters

    • type: K
    • listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

  • addEventListener(
        type: string,
        listener: EventListenerOrEventListenerObject,
        options?: boolean | AddEventListenerOptions,
    ): void

    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.

    Parameters

    • type: string
    • listener: EventListenerOrEventListenerObject
    • Optionaloptions: boolean | AddEventListenerOptions

    Returns void

connectedMoveCallback

  • connectedMoveCallback(): void

    Returns void

getContext

  • getContext(): Promise<Context>

    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 Promise<Context>

    a promise that resolves to the context when the loading has finished

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods