@needle-tools/engine/src/engine/webcomponents/needle-engine.attributes.ts

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.

type MainAttributes = {
    children?: HTMLElement[];
    style?: Partial<CSSStyleDeclaration>;
    /** src to one or multiple glb files to be loaded initially. Can be either "path/to/scene.glb" or "[./path/scene1.glb, myOtherScene.gltf]" */
    src?: string | string[];
    /** optional */
    hash?: string;
    /** set to automatically add OrbitControls to the loaded scene */
    "camera-controls"?: boolean | "none";
    /** event function name called when loading starts, use preventDefault to prevent the default loading overlay to show */
    "loadstart"?: string;
    /** event function name called when loading updates */
    "progress"?: string;
    /** event function name called when loading has finished */
    "loadfinished"?: string;
    /** override the default draco decoder path location */
    "dracoDecoderPath"?: string;
    /** override the default draco type */
    "dracoDecoderType"?: string;
    /** override the default ktx2 decoder path */
    "ktx2DecoderPath"?: string;

    /** Add to prevent Needle Engine context from being disposed when the element is removed from the DOM */
    "keep-alive"?: boolean;

    addEventListener?(event: "ready", callback: (event: CustomEvent) => void): void;
    addEventListener?(event: "error", callback: (event: CustomEvent) => void): void;
}

type LoadingAttributes = {
    /** Set a custom loading background color (e.g. "red" or "#dd00ff" or "rgba(18, 224, 224, 0.5)") */
    "loading-background"?: string,
    /** Pro features */
    "hide-loading-overlay"?: boolean,
    /** Pro feature */
    "loading-logo-src"?: string,
    /** Pro feature */
    "primary-color"?: string,
    /** Pro feature */
    "secondary-color"?: string,
}

type SkyboxAttributes = {
    /** @deprecated. Use background-image instead - URL to .exr, .hdr, .png, .jpg to be used as skybox */
    "skybox-image"?: string,
    /** URL to .exr, .hdr, .png, .jpg to be used as skybox */
    "background-image"?: string, 
    /** Blurs the background image (if any) - value between 0 and 1  
     * 0: no blur
     * 1: full blur
     */
    "background-blurriness"?: number,
    /**
     * Background color to be used if no skybox or background image is provided.  
     * For example: "skybox-color='#ff0000'" will set the background color to red.
     */
    "background-color"?: string,
    /** URL to .exr, .hdr, .png, .jpg to be used for lighting */
    "environment-image"?: string,
}

export type TonemappingAttributeOptions = "none" | "linear" | "neutral" | "agx";
type RenderingAttributes = {
    "transparent"?: boolean,
    "contactshadows"?: boolean,
    "tone-mapping"?: TonemappingAttributeOptions,
    "tone-mapping-exposure"?: number,
}

/**
 * Available attributes for the `<needle-engine>` web component
 * @inheritdoc
 */
export type NeedleEngineAttributes =
    MainAttributes
    & Partial<Omit<HTMLElement, "style">>
    & LoadingAttributes
    & SkyboxAttributes
    & RenderingAttributes
    ;