<needle-engine> Configuration

The <needle-engine> web-component comes with a nice collection of built-in attributes that can be used to modify the look and feel of the loaded scene without the need to add or edit the three.js scene directly. The table below shows a list of the most important ones:

Attribute	Description
Loading
src	Path to one or multiple glTF or glb files. Supported types are string, string[] or a stringified array (, separated)
dracoDecoderPath	URL to the draco decoder e.g. ./include/draco/ to use the local Draco decoder
dracoDecoderType	draco decoder type. Options are wasm or js. See three.js documentation
ktx2DecoderPath	URL to the KTX2 decoder e.g. ./include/ktx2/ to use the local KTX2 decoder
Rendering
background-color	optional, hex color to be used as a background color. Examples: rgb(255, 200, 100), #dddd00
background-image	optional, URL to a skybox image (background image) or a preset string: studio, blurred-skybox, quicklook, quicklook-ar
background-blurriness	optional, bluriness value between 0 (no blur) and 1 (max blur) for the background-image. Example: background-blurriness="0.5"
environment-image	optional, URL to a environment image (environment light) or a preset string: studio, blurred-skybox, quicklook, quicklook-ar
contactshadows	optional, render contact shadows
tone-mapping	optional, supported values are none, linear, neutral, agx
tone-mapping-exposure	optional number e.g. increase exposure with tone-mapping-exposure="1.5", requires tone-mapping to be set
Interaction
autoplay	add or set to true to auto play animations e.g. <needle-engine autoplay
camera-controls	add or set to true to automatically add OrbitControls if no camera controls are found in the scene
auto-rotate	add to enable auto-rotate (only used with camera-controls)
Events
loadstart	Name of the function to call when loading starts. Note that the arguments are (ctx:Context, evt:Event). You can call evt.preventDefault() to hide the default loading overlay
progress	Name of the function to call when loading updates. onProgress(ctx:Context, evt: {detail: {context:Context, name:string, index:number, count:number, totalProgress01:number}) { ... }
loadfinished	Name of the function to call when loading finishes
Loading Display	Available options to change how the Needle Engine loading display looks. Use ?debugloadingrendering for easier editing
loading-background	PRO — Default: transparent. Change the loading background color (e.g. #dd5500)
loading-logo-src	PRO — Change the loading logo image (e.g. https://yourdomain.com/logo.png or /logo.png)
hide-loading-overlay	PRO — Do not show the loading overlay
Internal
hash	Used internally, is appended to the files being loaded to force an update (e.g. when the browser has cached a glb file). Should not be edited manually.

Upgrade notice:

• Removed attributes in Needle Engine 4.5.0 loading-style, loading-background-color, loading-text-color, primary-color, secondary-color

Examples

<!-- Setting the path to a custom glb to be loaded -->
<needle-engine src="path/to/your.glb"></needle-engine>

<!-- Overriding where the draco decoder is located -->
<needle-engine src="path/to/your.glb" dracoDecoderPath="./include/draco/"></needle-engine>

Setting environment images, playing animation and automatic camera controls. See it live on stackblitz

<needle-engine
      camera-controls
      auto-rotate
      autoplay
      skybox-image="https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/industrial_sunset_puresky_1k.hdr"
      environment-image="https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/industrial_sunset_puresky_1k.hdr"
      src="https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/DamagedHelmet/glTF-Embedded/DamagedHelmet.gltf"
      >
      </needle-engine>

Receiving an event when the needle-engine context has finished loading:

<needle-engine loadfinished="onLoadFinished"> </needle-engine>
<script>
    function onLoadFinished() {
        console.log("Needle Engine has finished loading");
    }
</script>

Custom Loading Style (PRO)

You can easily modify how Needle Engine looks by setting the appropriate attributes on the <needle-engine> web component. Please see the table above for details.

See code on github